mimicry/browser.js

684 lines
25 KiB
JavaScript

"use strict";
const Mimicry = (function privateMimicryClosure () {
class Mimicry {
/**
* Creates an instance of the Mimicry.
*
* @param {Object} [config] - configuration of the Mimicry.
* @param {Number} [config.maxParallelLoadings] - amount of files that are loaded in parallel.
* @param {String} [config.baseUrl] - URL prefix that will be added to every.
* @param {String} [config.seed] - request optional component allowing to drop user cached files.
*/
constructor (config) {
instances.push(this);
this._queue = null; //deferred Queue
this._loadedFiles = new Set();
this._config = Object.create(null);
this._loadingFiles = new Map();
this._plannedFiles = Object.create(null);
this._modules = new Map();
this._typePaths = new Map();
this._loadedAssets = new Map();
this._libs = new Map();
this._errors = new Map();
this._moduleErrors = [];
this._errorHandlers = [];
this._progressHandlers = [];
Object.assign(this._config, defaultOptions, config);
this._baseUrl = this._config.baseUrl;
if (this._baseUrl && !this._baseUrl.endsWith("/"))
this._baseUrl += "/";
this._globalErrorHandler = onGlobalError.bind(this);
window.addEventListener("error", this._globalErrorHandler);
if (ready)
createDeferredParts.call(this);
else
this._deferred = [];
}
/**
* Finalizes Mimicry, clears as much memory as it can, forgets all the handlers and contexts
* */
destructor () {
window.off("error", this._globalErrorHandler);
const index = instances.indexOf(this);
instances.splice(index, 1);
delete this._queue;
delete this._loadedFiles;
delete this._config;
delete this._loadingFiles;
delete this._plannedFiles;
delete this._modules;
delete this._typePaths;
delete this._loadedAssets;
delete this._libs;
delete this._errors;
delete this._moduleErrors;
delete this._errorHandlers;
delete this._progressHandlers;
delete this._globalErrorHandler;
delete this._deferred;
delete this._baseUrl;
this.destroyed = true;
}
/**
* Loads a file, calls the callback if it has loaded successfully,
* calls error callback if there was any sort of error
*
* @param {String} path - path to the module
* @param {Function} [callback=contentType] - a callback that is called after module is loaded
* @param {Function} [error=contentType] - a callback that is called if there was an error
* @param {Mimicry.Type} [contentType=Mimicry.Type.js] - type of the content to load
*/
load (path, callback, error, contentType) {
if (!ready) {
this._deferred.push(["load", path, callback, error, contentType]);
return;
}
if (!(error instanceof Function) && contentType === undefined) {
contentType = error;
error = undefined;
}
if (!(callback instanceof Function) && contentType === undefined) {
contentType = callback;
callback = undefined;
}
if (!contentType)
contentType = Type.js;
scheduleLoad.call(this,
Dependency.refinePath(path, contentType, this._baseUrl, this._typePaths, this._libs),
callback, error, contentType, path);
}
/**
* Declares a module.
* The mainstream way to use Mimicry is to declare modules.
* It's best If you declare one module per file.
*
* The best way to export anything from the module is to return it from the callback
*
* @param {Array<String>} dependencies - list of module names that this module depends on
* @param {Function} [callback] - module body that will be executed as soon all dependencies are resolved
* @param {HTMLScriptElement} [script] - script element launching this module (you don't need to pass it, it's automatic)
*/
module (dependencies, callback, script) {
if (!ready) {
this._deferred.push(["module", dependencies, callback, document.currentScript]);
return;
}
const href = getCurrentHref(script);
if (!href.length)
throw new Error("Couldn't understand module path");
const moduleName = Dependency.nameFromHref(href, this._baseUrl, this._typePaths, this._libs);
if (this._modules.has(moduleName))
throw new Error("An attempt to declare more than one module per file (" + moduleName + ")");
const {deps, body} = Dependency.refineModuleArguments(dependencies, callback);
const module = new Module(deps, body);
this._modules.set(moduleName, module);
for (let i = 0; i < deps.length; ++i) {
const element = deps[i];
const contentType = element.contentType;
const elName = element.name;
this.load(elName, loadedFileForModule.bind(this, module, elName), contentType);
}
if (module.allDependenciesResolved)
module.execute(this, window);
}
/**
* Synchronously returns the module value if it was
* already loaded and executed, returns undefined otherwise
* */
getModule(/*String*/moduleName) {
const module = this._modules.get(moduleName);
if (module && module.executed)
return module.value;
}
/**
* Synchronously returns the asses if it was already loaded, returns undefined otherwise
* */
getAsset(/*String*/assetName) {
const asset = this._loadedAssets.get(assetName);
if (asset)
return asset;
}
/**
* If you wish to keep all files of some types in a designated folder of your project
* you can declare it using this function.
*
* Say, you want to have all JSON files in "json" folder, and all CSS files in "styles/css" folder.
* After calling "mimicry.setTypePath(Mimicry.Type.json, 'json')" and
* "mimicry.setTypePath(Mimicry.Type.css, 'styles/css')" you can access files from those folders
* in a following manner
*
* "mimicry.load('json/config/main', () => {}, Mimicry.Type.json)" changes to
* "mimicry.load('config/main', () => {}, Mimicry.Type.json)", and
*
* "mimicry.load('styles/css/basic', () => {}, Mimicry.Type.css)" to
* "mimicry.load('basic', () => {}, Mimicry.Type.css)"
* */
setTypePath (/*Type*/type, /*String*/path) {
if (path && !path.endsWith("/"))
path += "/";
this._typePaths.set(type, path);
}
/**
* You might want to include other projects in your project. I will call those imported subprojects libraries
* In mimicry there is a way to hide actual path behind library name.
*
* Say you included a library called "flame", and placed in "libs/external/flame".
* After calling "mimicry.setLibPath('flame', 'libs/external/flame')" you can access files from those libraries
* in a following manner
*
* "mimicry.load('libs/external/flame/index', () => {})" changes to
* "mimicry.load('@flame/index', () => {})"
* */
setLibPath (/*String*/libraryName, /*String*/libraryPath) {
const path = this._libs.get(libraryName);
if (path && path !== libraryPath)
throw new Error("Mimicry error: library " + libraryName + " already had a path " + path +
", assigning new path " + libraryPath + " would probably break everything");
this._libs.set(libraryName, libraryPath);
}
/**
* Adds a handler for you to handle errors that this instance of mimicry
* faces loading and evaluating files.
*
* These handlers get called after (if there was any) error callbacks passed to load operations.
*
* @param {Function} handler - a handler that would be called in case of error
*
* Handler is called with a single argument of error, which can one of the following types:
* - Mimicry.FileError - if there was an error on file evaluation
* - Mimicry.LoadError - if mimicry could not load a file
* */
addErrorHandler (handler) {
this._errorHandlers.push(handler);
}
/**
* Method provides you information about the progress of your loads.
* Sometimes when you load lots of files in bulk you wish to show a progress indicator.
*
* @param {Function} handler - a handler which is called when the progress changes
* Passed handler is called with following arguments:
* {Number} loaded - how many files mimicry have loaded so far
* {Number} pending - how many files are currently loading or in a queue
* {Number} total - how many files does mimicry even know about
* */
addProgressHandler (handler) {
this._progressHandlers.push(handler);
}
/**
* If you use Mimicry in a script file included right after mimicry
* it might not be able to work yet: it doesn't yet have some classes for normal work.
* In this "unready" state you can not
* - access Mimicry.FileError nad Mimicry.LoadError classes
* - access Mimicry.Type enum.
*
* You can, however, perform default (meaning Mimicry.type.js) loads, declare modules,
* set up paths, and subscribe to handlers.
*
* @returns {Boolean} - if the instance is ready to be used
* */
get ready () {return ready;}
/**
* @returns {Number} - amount of files that are currently loading or in a queue
* */
get pendingFilesAmount () {return this._loadingFiles.size + this._queue.length;}
/**
* @returns {Number} - amount of files mimicry have loaded until this moment
* */
get loadedFilesAmount () {return this._loadedFiles.size;}
/**
* @returns {Object} - default mimicry options object
* */
static get defaultOptions () {return defaultOptions;}
/**
* If you use Mimicry in a script file included right after mimicry
* it might not be able to work yet: it doesn't yet have some classes for normal work.
* In this "unready" state you can not
* - access Mimicry.FileError nad Mimicry.LoadError classes
* - access Mimicry.Type enum.
*
* You can, however, perform default (meaning Mimicry.type.js) loads, declare modules,
* set up paths, and subscribe to handlers.
*
* This state is on the static level: once all necessary files are loaded all mimicry instances are
* ready and don't need to be waited on
*
* @returns {Boolean} - if the Mimicry system is ready to be used
* */
static get ready () {return ready;}
/**
* Normally mimicry loads .js files, but you can also load other stuff like json, or css, or binary
* I expect you to pass values from this enum to specify what exactly you are loading if it is not a
* JavaScript file
*
* @returns {Mimicry.Type} - type of content
* */
static get Type () {return Type;}
static get FileError() {return FileError;}
static get LoadError() {return LoadError;}
}
const defaultOptions = {
maxParallelLoadings: 10,
baseUrl: "",
seed: ""
};
Object.freeze(defaultOptions)
function createDeferredParts () {
this._queue = new Queue();
}
function launchDeferredRequests () {
if (this._deferred instanceof Array) {
while (this._deferred.length) {
const args = this._deferred.shift();
const methodName = args.shift();
this[methodName].apply(this, args);
}
delete this._deferred;
}
}
function callCallback(/*Function*/callback, /*String*/originalName) {
if (callback instanceof Function) {
const module = this._modules.get(originalName);
if (module) {
module.addCallback(callback, window);
} else {
const asset = this._loadedAssets.get(originalName);
if (asset)
callback(asset);
else
callback(window);
}
}
}
/**
* @param {String} path
* @param {Function} callback
* @param {Function} error
* @param {Type} contentType
* @param {String} originalName
* */
function scheduleLoad (path, callback, error, contentType, originalName) {
if (this._loadedFiles.has(path))
return callCallback.call(this, callback, originalName);
let loadingFile = this._loadingFiles.get(path);
if (loadingFile === undefined)
loadingFile = this._plannedFiles[path];
if (loadingFile) {
Dependency.checkContentType(loadingFile.contentType, contentType, path);
loadingFile.addSuccessHandler(callback);
loadingFile.addErrorHandler(error);
return;
}
loadingFile = new LoadingFile(contentType, originalName, callback, error);
if (this._loadingFiles.size < this._config.maxParallelLoadings) {
executeLoad.call(this, path, loadingFile);
} else {
this._queue.push(path);
this._plannedFiles[path] = loadingFile;
}
notifyProgressSubscribers.call(this);
}
function executeLoad (/*String*/path, /*LoadingFile*/loadingFile) {
this._loadingFiles.set(path, loadingFile);
const boundLoad = onLoaded.bind(this, path);
const boundError = onError.bind(this, path);
switch (loadingFile.contentType) {
case Type.js:
getScriptWithTag(path, boundLoad, boundError, this._config.seed);
break;
case Type.css:
getStylesheetWithTag(path, boundLoad, boundError, this._config.seed);
break;
case Type.json:
getByXHR(path, boundLoad, boundError, "json", this._config.seed);
break;
case Type.binary:
getByXHR(path, boundLoad, boundError, "arraybuffer", this._config.seed);
break;
case Type.text:
getByXHR(path, boundLoad, boundError, "text", this._config.seed);
break;
}
}
function notifyProgressSubscribers() {
const pending = this.pendingFilesAmount;
const loaded = this.loadedFilesAmount;
for (let i = 0; i < this._progressHandlers.length; ++i) {
const handler = this._progressHandlers[i];
handler(loaded, pending, loaded + pending);
}
}
function onLoaded(/*String*/path, /*HTMLScriptElement*/event) {
if (this._moduleErrors.length)
return onModuleError.call(this, path, event);
if (this._errors.has(path))
return onError.call(this, path, event);
const loading = this._loadingFiles.get(path);
this._loadedFiles.add(path);
switch (loading.contentType) {
case Type.json:
case Type.binary:
case Type.text:
this._loadedAssets.set(loading.originalName, event.target.response);
break;
}
loading.callSuccessHandlers(callCallback, this);
cleanUp.call(this, path, event);
checkNextElement.call(this);
notifyProgressSubscribers.call(this);
}
function onError (/*String*/path, /*HTMLScriptElement*/element) {
const loading = this._loadingFiles.get(path);
let error = this._errors.get(path);
if (!(error instanceof BasicError))
error = new LoadError(path, loading.originalName);
loading.callErrorHandlers(error);
for (let i = 0; i < this._errorHandlers.length; ++i)
this._errorHandlers[i](error);
cleanUp.call(this, path, element);
checkNextElement.call(this);
notifyProgressSubscribers.call(this);
}
function onModuleError (/*String*/path, /*HTMLScriptElement*/element) {
for (let i = 0; i < this._moduleErrors.length; ++i) {
const error = this._moduleErrors[i];
error.path = path;
for (let i = 0; i < this._errorHandlers.length; ++i)
this._errorHandlers[i](error)
}
this._moduleErrors = [];
cleanUp.call(this, path, element);
checkNextElement.call(this);
notifyProgressSubscribers.call(this);
}
function cleanUp (/*String*/path, /*Event*/element) {
const loading = this._loadingFiles.get(path);
this._loadingFiles.delete(path);
this._errors.delete(path);
switch (loading.contentType) {
case Type.js:
cleanTag(element.target);
break;
case Type.css:
cleanUpHandlers(element.target);
break;
case Type.json:
case Type.binary:
case Type.text:
cleanUpHandlers(element);
break
}
loading.destructor();
}
function cleanTag (/*HTMLElement or Event*/tag) {
tag.remove();
cleanUpHandlers(tag);
}
function cleanUpHandlers (/*HTMLElement*/tag) {
delete tag.onload;
delete tag.onerror;
}
function onGlobalError (event, url, line, col, errorObj) {
let message;
if (event instanceof ErrorEvent) {
url = event.filename;
line = event.lineno;
col = event.colno;
errorObj = event.error;
message = event.message;
} else {
message = event;
}
if (url && url.indexOf(location.origin) === 0)
url = url.slice(location.origin.length);
if (!setFileError(url, message, line, col, errorObj)) {
let href = getCurrentHref();
const index = url.lastIndexOf(href);
if (href.length && index === url.length - href.length)
setFileError(href, message, line, col, errorObj)
}
}
function setFileError(name, message, line, col, errorObj) {
let result = true;
let loading = this._loadingFiles.get(name);
if (loading instanceof LoadingFile)
this._errors.set(name, new FileError(name, loading.originalName, message, line, col, errorObj));
else
result = false;
return result;
}
function checkNextElement () {
while (!this._queue.empty && (this._loadingFiles.size < this._config.maxParallelLoadings)) {
const path = this._queue.pop();
const loadingFile = this._plannedFiles[path];
delete this._plannedFiles[path];
executeLoad.call(this, path, loadingFile);
}
}
/**
* @param {String} path - path of the file you wish to load
* @param {Function} [callback] - handler that would be called upon successful load
* @param {Function} [error] - handler that would ba called upon error
* @param {String} [seed] - a short seed to avoid unwanted caching
* */
function getScriptWithTag (path, callback, error, seed) {
const tag = document.createElement("script");
tag.setAttribute("async", "");
document.head.appendChild(tag);
tag.onload = callback;
tag.onerror = error;
if (seed)
path += "?seed=" + seed;
tag.src = path;
}
/**
* @param {String} path - path of the file you wish to load
* @param {Function} [callback] - handler that would be called upon successful load
* @param {Function} [error] - handler that would ba called upon error
* @param {String} [seed] - a short seed to avoid unwanted caching
* */
function getStylesheetWithTag (path, callback, error, seed) {
const tag = document.createElement("link");
tag.setAttribute("type", "text/css");
tag.setAttribute("rel", "stylesheet");
document.head.appendChild(tag);
tag.onload = callback;
tag.onerror = error;
if (seed)
path += "?seed=" + seed;
tag.href = path;
}
/**
* @param {String} url
* @param {Function} callback
* @param {Function} error
* @param {XMLHttpRequestResponseType} [responseType="arraybuffer"]
* @param {String} [seed=""]
* */
function getByXHR (url, callback, error, responseType="arraybuffer", seed="") {
const xhr = new XMLHttpRequest();
if (seed)
url += "?seed=" + seed;
xhr.open("GET", url, true);
xhr.responseType = responseType;
xhr.onload = callback.bind(xhr);
xhr.onerror = error.bind(xhr);
xhr.send();
}
function getCurrentHref(src) {
let possible = document.currentScript;
if (src instanceof HTMLScriptElement)
possible = src;
const script = possible || launcher;
if (script instanceof HTMLScriptElement)
return script.attributes.src.value;
else
return "";
}
function loadedFileForModule (/*Module*/requester, /*String*/fileName) {
const dep = this._modules.get(fileName);
if (dep)
dep.addCallback(requester.incrementDependency.bind(requester, this, window), window);
else
requester.incrementDependency(this, window);
}
const launcher = document.currentScript;
const instances = [];
let BasicError, LoadError, FileError;
let LoadingFile;
let Queue;
let Dependency, Type;
let Module;
let ready = false;
let errorsReady = false;
let fileReady = false;
let queueReady = false;
let dependencyReady = false;
let moduleReady = false;
function checkDeferred () {
if (!ready) {
if (errorsReady && fileReady && queueReady && dependencyReady && moduleReady) {
ready = true;
for (let i = 0; i < instances.length; ++i) {
const instance = instances[i];
createDeferredParts.call(instance);
launchDeferredRequests.call(instance);
}
if (launcher instanceof HTMLScriptElement) {
const main = launcher.dataset.main
if (main)
getScriptWithTag(main);
}
}
}
}
const src = launcher.src.split("/");
src.pop();
let pathPrefix = src.join('/');
if (pathPrefix !== "")
pathPrefix += "/";
getScriptWithTag(pathPrefix + "errors.js", function (event) {
cleanTag(event.target);
BasicError = window.__MimicryErrors__.BasicError;
LoadError = window.__MimicryErrors__.LoadError;
FileError = window.__MimicryErrors__.FileError;
delete window.__MimicryErrors__;
errorsReady = true;
checkDeferred();
});
getScriptWithTag(pathPrefix + "loadingFile.js", function (event) {
cleanTag(event.target);
LoadingFile = window.__MimicryLoadingFile__;
delete window.__MimicryLoadingFile__;
fileReady = true;
checkDeferred();
});
getScriptWithTag(pathPrefix + "queue.js", function (event) {
cleanTag(event.target);
Queue = window.__MimicryQueue__;
delete window.__MimicryQueue__;
queueReady = true;
checkDeferred();
});
getScriptWithTag(pathPrefix + "dependency.js", function (event) {
cleanTag(event.target);
Dependency = window.__MimicryDependency__;
Type = Dependency.Type;
delete window.__MimicryDependency__;
dependencyReady = true;
checkDeferred();
});
getScriptWithTag(pathPrefix + "module.js", function (event) {
cleanTag(event.target);
Module = window.__MimicryModule__;
delete window.__MimicryModule__;
moduleReady = true;
checkDeferred();
});
return Mimicry;
})();