@atlaspack/core 2.12.1-canary.3354

package/lib/resolveOptions.js

@@ -0,0 +1,234 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = resolveOptions;
+function _path() {
+  const data = _interopRequireDefault(require("path"));
+  _path = function () {
+    return data;
+  };
+  return data;
+}
+function _rust() {
+  const data = require("@atlaspack/rust");
+  _rust = function () {
+    return data;
+  };
+  return data;
+}
+function _fs() {
+  const data = require("@atlaspack/fs");
+  _fs = function () {
+    return data;
+  };
+  return data;
+}
+function _cache() {
+  const data = require("@atlaspack/cache");
+  _cache = function () {
+    return data;
+  };
+  return data;
+}
+function _packageManager() {
+  const data = require("@atlaspack/package-manager");
+  _packageManager = function () {
+    return data;
+  };
+  return data;
+}
+function _utils() {
+  const data = require("@atlaspack/utils");
+  _utils = function () {
+    return data;
+  };
+  return data;
+}
+var _loadDotEnv = _interopRequireDefault(require("./loadDotEnv"));
+var _projectPath = require("./projectPath");
+var _AtlaspackConfigRequest = require("./requests/AtlaspackConfigRequest");
+function _featureFlags() {
+  const data = require("@atlaspack/feature-flags");
+  _featureFlags = function () {
+    return data;
+  };
+  return data;
+}
+var _constants = require("./constants");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+// Default cache directory name
+const DEFAULT_CACHE_DIRNAME = '.atlaspack-cache';
+const LOCK_FILE_NAMES = ['yarn.lock', 'package-lock.json', 'pnpm-lock.yaml'];
+
+// Generate a unique instanceId, will change on every run of atlaspack
+function generateInstanceId(entries) {
+  return (0, _rust().hashString)(`${entries.join(',')}-${Date.now()}-${Math.round(Math.random() * 100)}`);
+}
+
+// Compiles an array of globs to regex - used for lazy include/excludes
+function compileGlobs(globs) {
+  return globs.map(glob => (0, _utils().globToRegex)(glob));
+}
+async function resolveOptions(initialOptions) {
+  var _initialOptions$defau, _initialOptions$defau2, _initialOptions$defau3, _initialOptions$defau4, _initialOptions$addit, _initialOptions$defau5, _initialOptions$defau6, _initialOptions$defau7, _initialOptions$defau8, _initialOptions$defau9;
+  let inputFS = initialOptions.inputFS || new (_fs().NodeFS)();
+  let outputFS = initialOptions.outputFS || new (_fs().NodeFS)();
+  let inputCwd = inputFS.cwd();
+  let outputCwd = outputFS.cwd();
+  let entries;
+  if (initialOptions.entries == null || initialOptions.entries === '') {
+    entries = [];
+  } else if (Array.isArray(initialOptions.entries)) {
+    entries = initialOptions.entries.map(entry => _path().default.resolve(inputCwd, entry));
+  } else {
+    entries = [_path().default.resolve(inputCwd, initialOptions.entries)];
+  }
+  let shouldMakeEntryReferFolder = false;
+  if (entries.length === 1 && !(0, _utils().isGlob)(entries[0])) {
+    let [entry] = entries;
+    try {
+      shouldMakeEntryReferFolder = (await inputFS.stat(entry)).isDirectory();
+    } catch {
+      // ignore failing stat call
+    }
+  }
+
+  // getRootDir treats the input as files, so getRootDir(["/home/user/myproject"]) returns "/home/user".
+  // Instead we need to make the the entry refer to some file inside the specified folders if entries refers to the directory.
+  let entryRoot = (0, _utils().getRootDir)(shouldMakeEntryReferFolder ? [_path().default.join(entries[0], 'index')] : entries);
+  let projectRootFile = (await (0, _utils().resolveConfig)(inputFS, _path().default.join(entryRoot, 'index'), [...LOCK_FILE_NAMES, '.git', '.hg'], _path().default.parse(entryRoot).root)) || _path().default.join(inputCwd, 'index'); // ? Should this just be rootDir
+
+  let projectRoot = _path().default.dirname(projectRootFile);
+  let packageManager = initialOptions.packageManager || new (_packageManager().NodePackageManager)(inputFS, projectRoot);
+  let cacheDir =
+  // If a cacheDir is provided, resolve it relative to cwd. Otherwise,
+  // use a default directory resolved relative to the project root.
+  initialOptions.cacheDir != null ? _path().default.resolve(outputCwd, initialOptions.cacheDir) : _path().default.resolve(projectRoot, DEFAULT_CACHE_DIRNAME);
+
+  // Make the root watch directory configurable. This is useful in some cases
+  // where symlinked dependencies outside the project root need to trigger HMR
+  // updates. Default to the project root if not provided.
+  let watchDir = initialOptions.watchDir != null ? _path().default.resolve(initialOptions.watchDir) : projectRoot;
+  let cache = initialOptions.cache ?? (outputFS instanceof _fs().NodeFS ? new (_cache().LMDBCache)(cacheDir) : new (_cache().FSCache)(outputFS, cacheDir));
+  let mode = initialOptions.mode ?? 'development';
+  let shouldOptimize = (initialOptions === null || initialOptions === void 0 || (_initialOptions$defau = initialOptions.defaultTargetOptions) === null || _initialOptions$defau === void 0 ? void 0 : _initialOptions$defau.shouldOptimize) ?? mode === 'production';
+  let publicUrl = (initialOptions === null || initialOptions === void 0 || (_initialOptions$defau2 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau2 === void 0 ? void 0 : _initialOptions$defau2.publicUrl) ?? '/';
+  let distDir = (initialOptions === null || initialOptions === void 0 || (_initialOptions$defau3 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau3 === void 0 ? void 0 : _initialOptions$defau3.distDir) != null ? _path().default.resolve(inputCwd, initialOptions === null || initialOptions === void 0 || (_initialOptions$defau4 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau4 === void 0 ? void 0 : _initialOptions$defau4.distDir) : undefined;
+  let shouldBuildLazily = initialOptions.shouldBuildLazily ?? false;
+  let lazyIncludes = compileGlobs(initialOptions.lazyIncludes ?? []);
+  if (lazyIncludes.length > 0 && !shouldBuildLazily) {
+    throw new Error('Lazy includes can only be provided when lazy building is enabled');
+  }
+  let lazyExcludes = compileGlobs(initialOptions.lazyExcludes ?? []);
+  if (lazyExcludes.length > 0 && !shouldBuildLazily) {
+    throw new Error('Lazy excludes can only be provided when lazy building is enabled');
+  }
+  let shouldContentHash = initialOptions.shouldContentHash ?? initialOptions.mode === 'production';
+  if (shouldBuildLazily && shouldContentHash) {
+    throw new Error('Lazy bundling does not work with content hashing');
+  }
+  let env = {
+    ...(await (0, _loadDotEnv.default)(initialOptions.env ?? {}, inputFS, _path().default.join(projectRoot, 'index'), projectRoot)),
+    ...process.env,
+    ...initialOptions.env
+  };
+  let port = determinePort(initialOptions.serveOptions, env.PORT);
+  return {
+    config: getRelativeConfigSpecifier(inputFS, projectRoot, initialOptions.config),
+    defaultConfig: getRelativeConfigSpecifier(inputFS, projectRoot, initialOptions.defaultConfig),
+    shouldPatchConsole: initialOptions.shouldPatchConsole ?? false,
+    env,
+    mode,
+    shouldAutoInstall: initialOptions.shouldAutoInstall ?? false,
+    hmrOptions: initialOptions.hmrOptions ?? null,
+    shouldBuildLazily,
+    lazyIncludes,
+    lazyExcludes,
+    unstableFileInvalidations: initialOptions.unstableFileInvalidations,
+    shouldBundleIncrementally: initialOptions.shouldBundleIncrementally ?? true,
+    shouldContentHash,
+    serveOptions: initialOptions.serveOptions ? {
+      ...initialOptions.serveOptions,
+      distDir: distDir ?? _path().default.join(outputCwd, 'dist'),
+      port
+    } : false,
+    shouldDisableCache: initialOptions.shouldDisableCache ?? false,
+    shouldProfile: initialOptions.shouldProfile ?? false,
+    shouldTrace: initialOptions.shouldTrace ?? false,
+    cacheDir,
+    watchDir,
+    watchBackend: initialOptions.watchBackend,
+    watchIgnore: initialOptions.watchIgnore,
+    entries: entries.map(e => (0, _projectPath.toProjectPath)(projectRoot, e)),
+    targets: initialOptions.targets,
+    logLevel: initialOptions.logLevel ?? 'info',
+    projectRoot,
+    inputFS,
+    outputFS,
+    cache,
+    packageManager,
+    additionalReporters: ((_initialOptions$addit = initialOptions.additionalReporters) === null || _initialOptions$addit === void 0 ? void 0 : _initialOptions$addit.map(({
+      packageName,
+      resolveFrom
+    }) => ({
+      packageName,
+      resolveFrom: (0, _projectPath.toProjectPath)(projectRoot, resolveFrom)
+    }))) ?? [],
+    instanceId: generateInstanceId(entries),
+    detailedReport: initialOptions.detailedReport,
+    defaultTargetOptions: {
+      shouldOptimize,
+      shouldScopeHoist: initialOptions === null || initialOptions === void 0 || (_initialOptions$defau5 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau5 === void 0 ? void 0 : _initialOptions$defau5.shouldScopeHoist,
+      sourceMaps: (initialOptions === null || initialOptions === void 0 || (_initialOptions$defau6 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau6 === void 0 ? void 0 : _initialOptions$defau6.sourceMaps) ?? true,
+      publicUrl,
+      ...(distDir != null ? {
+        distDir: (0, _projectPath.toProjectPath)(projectRoot, distDir)
+      } : {
+        /*::...null*/
+      }),
+      engines: initialOptions === null || initialOptions === void 0 || (_initialOptions$defau7 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau7 === void 0 ? void 0 : _initialOptions$defau7.engines,
+      outputFormat: initialOptions === null || initialOptions === void 0 || (_initialOptions$defau8 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau8 === void 0 ? void 0 : _initialOptions$defau8.outputFormat,
+      isLibrary: initialOptions === null || initialOptions === void 0 || (_initialOptions$defau9 = initialOptions.defaultTargetOptions) === null || _initialOptions$defau9 === void 0 ? void 0 : _initialOptions$defau9.isLibrary
+    },
+    featureFlags: {
+      ..._featureFlags().DEFAULT_FEATURE_FLAGS,
+      ...(initialOptions === null || initialOptions === void 0 ? void 0 : initialOptions.featureFlags)
+    },
+    atlaspackVersion: _constants.ATLASPACK_VERSION
+  };
+}
+function getRelativeConfigSpecifier(fs, projectRoot, specifier) {
+  if (specifier == null) {
+    return undefined;
+  } else if (_path().default.isAbsolute(specifier)) {
+    let resolveFrom = (0, _AtlaspackConfigRequest.getResolveFrom)(fs, projectRoot);
+    let relative = (0, _utils().relativePath)(_path().default.dirname(resolveFrom), specifier);
+    // If the config is outside the project root, use an absolute path so that if the project root
+    // moves the path still works. Otherwise, use a relative path so that the cache is portable.
+    return relative.startsWith('..') ? specifier : relative;
+  } else {
+    return specifier;
+  }
+}
+function determinePort(initialServerOptions, portInEnv, defaultPort = 1234) {
+  function parsePort(port) {
+    let parsedPort = Number(port);
+
+    // return undefined if port number defined in .env is not valid integer
+    if (!Number.isInteger(parsedPort)) {
+      return undefined;
+    }
+    return parsedPort;
+  }
+  if (!initialServerOptions) {
+    return typeof portInEnv !== 'undefined' ? parsePort(portInEnv) ?? defaultPort : defaultPort;
+  }
+
+  // if initialServerOptions.port is equal to defaultPort, then this means that port number is provided via PORT=~~~~ on cli. In this case, we should ignore port number defined in .env.
+  if (initialServerOptions.port !== defaultPort) {
+    return initialServerOptions.port;
+  }
+  return typeof portInEnv !== 'undefined' ? parsePort(portInEnv) ?? defaultPort : defaultPort;
+}

package/lib/serializer.js

@@ -0,0 +1,216 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.cacheSerializedObject = cacheSerializedObject;
+exports.deserialize = deserialize;
+Object.defineProperty(exports, "deserializeRaw", {
+  enumerable: true,
+  get: function () {
+    return _serializerCore.deserializeRaw;
+  }
+});
+exports.deserializeToCache = deserializeToCache;
+exports.prepareForSerialization = prepareForSerialization;
+exports.registerSerializableClass = registerSerializableClass;
+exports.removeSerializedObjectFromCache = removeSerializedObjectFromCache;
+exports.restoreDeserializedObject = restoreDeserializedObject;
+exports.serialize = serialize;
+Object.defineProperty(exports, "serializeRaw", {
+  enumerable: true,
+  get: function () {
+    return _serializerCore.serializeRaw;
+  }
+});
+exports.unregisterSerializableClass = unregisterSerializableClass;
+var _buildCache = require("./buildCache");
+var _serializerCore = require("./serializerCore");
+const nameToCtor = new Map();
+const ctorToName = new Map();
+function registerSerializableClass(name, ctor) {
+  if (ctorToName.has(ctor)) {
+    throw new Error('Class already registered with serializer');
+  }
+  nameToCtor.set(name, ctor);
+  ctorToName.set(ctor, name);
+}
+function unregisterSerializableClass(name, ctor) {
+  if (nameToCtor.get(name) === ctor) {
+    nameToCtor.delete(name);
+  }
+  if (ctorToName.get(ctor) === name) {
+    ctorToName.delete(ctor);
+  }
+}
+function shallowCopy(object) {
+  if (object && typeof object === 'object') {
+    if (Array.isArray(object)) {
+      return [...object];
+    }
+    if (object instanceof Map) {
+      return new Map(object);
+    }
+    if (object instanceof Set) {
+      return new Set(object);
+    }
+    return Object.create(Object.getPrototypeOf(object), Object.getOwnPropertyDescriptors(object));
+  }
+  return object;
+}
+function isBuffer(object) {
+  return object.buffer instanceof ArrayBuffer || typeof SharedArrayBuffer !== 'undefined' && object.buffer instanceof SharedArrayBuffer;
+}
+function shouldContinueMapping(value) {
+  return value && typeof value === 'object' && value.$$raw !== true;
+}
+function mapObject(object, fn, preOrder = false) {
+  let cache = new Map();
+  let memo = new Map();
+
+  // Memoize the passed function to ensure it always returns the exact same
+  // output by reference for the same input. This is important to maintain
+  // reference integrity when deserializing rather than cloning.
+  let memoizedFn = val => {
+    let res = memo.get(val);
+    if (res == null) {
+      res = fn(val);
+      memo.set(val, res);
+    }
+    return res;
+  };
+  let walk = (object, shouldCopy = false) => {
+    // Check the cache first, both for performance and cycle detection.
+    if (cache.has(object)) {
+      return cache.get(object);
+    }
+    let result = object;
+    cache.set(object, result);
+    let processKey = (key, value) => {
+      let newValue = value;
+      if (preOrder && value && typeof value === 'object') {
+        newValue = memoizedFn(value);
+      }
+
+      // Recursively walk the children
+      if (preOrder ? shouldContinueMapping(newValue) : newValue && typeof newValue === 'object' && shouldContinueMapping(object)) {
+        newValue = walk(newValue, newValue === value);
+      }
+      if (!preOrder && newValue && typeof newValue === 'object') {
+        newValue = memoizedFn(newValue);
+      }
+      if (newValue !== value) {
+        // Copy on write. We only need to do this when serializing, not deserializing.
+        if (object === result && preOrder && shouldCopy) {
+          result = shallowCopy(object);
+          cache.set(object, result);
+        }
+
+        // Replace the key with the new value
+        if (result instanceof Map) {
+          result.set(key, newValue);
+        } else if (result instanceof Set) {
+          let _result = result; // For Flow
+          // TODO: do we care about iteration order??
+          _result.delete(value);
+          _result.add(newValue);
+        } else {
+          result[key] = newValue;
+        }
+      }
+    };
+
+    // Iterate in various ways depending on type.
+    if (Array.isArray(object)) {
+      for (let i = 0; i < object.length; i++) {
+        processKey(i, object[i]);
+      }
+    } else if (object instanceof Map || object instanceof Set) {
+      for (let [key, val] of object.entries()) {
+        processKey(key, val);
+      }
+    } else if (!isBuffer(object)) {
+      for (let key in object) {
+        processKey(key, object[key]);
+      }
+    }
+    return result;
+  };
+  let mapped = memoizedFn(object);
+  if (preOrder ? shouldContinueMapping(mapped) : mapped && typeof mapped === 'object' && shouldContinueMapping(object)) {
+    return walk(mapped, mapped === object);
+  }
+  return mapped;
+}
+function prepareForSerialization(object) {
+  if (object !== null && object !== void 0 && object.$$raw) {
+    return object;
+  }
+  return mapObject(object, value => {
+    // Add a $$type property with the name of this class, if any is registered.
+    if (value && typeof value === 'object' && typeof value.constructor === 'function') {
+      let type = ctorToName.get(value.constructor);
+      if (type != null) {
+        let serialized = value;
+        let raw = false;
+        if (value && typeof value.serialize === 'function') {
+          // If the object has a serialize method, call it
+          serialized = value.serialize();
+          raw = (serialized && serialized.$$raw) ?? true;
+          if (serialized) {
+            delete serialized.$$raw;
+          }
+        }
+        return {
+          $$type: type,
+          $$raw: raw,
+          value: {
+            ...serialized
+          }
+        };
+      }
+    }
+    return value;
+  }, true);
+}
+function restoreDeserializedObject(object) {
+  return mapObject(object, value => {
+    // If the value has a $$type property, use it to restore the object type
+    if (value && value.$$type) {
+      let ctor = nameToCtor.get(value.$$type);
+      if (ctor == null) {
+        throw new Error(`Expected constructor ${value.$$type} to be registered with serializer to deserialize`);
+      }
+      if (typeof ctor.deserialize === 'function') {
+        return ctor.deserialize(value.value);
+      }
+      value = value.value;
+      Object.setPrototypeOf(value, ctor.prototype);
+    }
+    return value;
+  });
+}
+const serializeCache = (0, _buildCache.createBuildCache)();
+function serialize(object) {
+  let cached = serializeCache.get(object);
+  if (cached) {
+    return cached;
+  }
+  let mapped = prepareForSerialization(object);
+  return (0, _serializerCore.serializeRaw)(mapped);
+}
+function deserialize(buffer) {
+  let obj = (0, _serializerCore.deserializeRaw)(buffer);
+  return restoreDeserializedObject(obj);
+}
+function cacheSerializedObject(object, buffer) {
+  serializeCache.set(object, buffer || serialize(object));
+}
+function deserializeToCache(buffer) {
+  let deserialized = deserialize(buffer);
+  serializeCache.set(deserialized, buffer);
+  return deserialized;
+}
+function removeSerializedObjectFromCache(object) {
+  serializeCache.delete(object);
+}

package/lib/serializerCore.browser.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.serializeRaw = exports.deserializeRaw = void 0;
+function _buffer() {
+  const data = require("buffer");
+  _buffer = function () {
+    return data;
+  };
+  return data;
+}
+function msgpackr() {
+  const data = _interopRequireWildcard(require("msgpackr"));
+  msgpackr = function () {
+    return data;
+  };
+  return data;
+}
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+let encoder = new (msgpackr().Encoder)({
+  structuredClone: true
+});
+let serializeRaw = v => _buffer().Buffer.from(encoder.encode(v));
+exports.serializeRaw = serializeRaw;
+let deserializeRaw = v => encoder.decode(v);
+exports.deserializeRaw = deserializeRaw;

package/lib/serializerCore.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.serializeRaw = exports.deserializeRaw = void 0;
+function _v() {
+  const data = _interopRequireDefault(require("v8"));
+  _v = function () {
+    return data;
+  };
+  return data;
+}
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+let serializeRaw = exports.serializeRaw = _v().default.serialize;
+let deserializeRaw = exports.deserializeRaw = _v().default.deserialize;

package/lib/summarizeRequest.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = summarizeRequest;
+function _path() {
+  const data = _interopRequireDefault(require("path"));
+  _path = function () {
+    return data;
+  };
+  return data;
+}
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+const NODE_MODULES = `${_path().default.sep}node_modules${_path().default.sep}`;
+const BUFFER_LIMIT = 5000000; // 5mb
+
+async function summarizeRequest(fs, req) {
+  let {
+    content,
+    size
+  } = await summarizeDiskRequest(fs, req);
+  let isSource = isFilePathSource(fs, req.filePath);
+  return {
+    content,
+    size,
+    isSource
+  };
+}
+function isFilePathSource(fs, filePath) {
+  return !filePath.includes(NODE_MODULES);
+}
+async function summarizeDiskRequest(fs, req) {
+  let code = req.code;
+  let content;
+  let size;
+  if (code == null) {
+    // Get the filesize. If greater than BUFFER_LIMIT, use a stream to
+    // compute the hash. In the common case, it's faster to just read the entire
+    // file first and do the hash all at once without the overhead of streams.
+    size = (await fs.stat(req.filePath)).size;
+    if (size > BUFFER_LIMIT) {
+      content = fs.createReadStream(req.filePath);
+    } else {
+      content = await fs.readFile(req.filePath);
+    }
+  } else {
+    content = code;
+    size = Buffer.byteLength(code);
+  }
+  return {
+    content,
+    size
+  };
+}

package/lib/types.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SpecifierType = exports.Priority = exports.ExportsCondition = exports.BundleBehaviorNames = exports.BundleBehavior = void 0;
+const SpecifierType = exports.SpecifierType = {
+  esm: 0,
+  commonjs: 1,
+  url: 2,
+  custom: 3
+};
+const Priority = exports.Priority = {
+  sync: 0,
+  parallel: 1,
+  lazy: 2
+};
+
+// Must match package_json.rs in node-resolver-rs.
+const ExportsCondition = exports.ExportsCondition = {
+  import: 1 << 0,
+  require: 1 << 1,
+  module: 1 << 2,
+  style: 1 << 12,
+  sass: 1 << 13,
+  less: 1 << 14,
+  stylus: 1 << 15
+};
+const BundleBehavior = exports.BundleBehavior = {
+  inline: 0,
+  isolated: 1
+};
+const BundleBehaviorNames = exports.BundleBehaviorNames = Object.keys(BundleBehavior);
+
+// Asset group nodes are essentially used as placeholders for the results of an asset request