@vsaas/remoting 10.0.0

package/dist/lib/remote-objects.js

@@ -0,0 +1,642 @@
+"use strict";
+const require_runtime = require("../_virtual/_rolldown/runtime.js");
+const require_lib_messages = require("./messages.js");
+const require_lib_deprecate = require("./deprecate.js");
+const require_lib_type_registry = require("./type-registry.js");
+require("./shared-method.js");
+const require_lib_shared_class = require("./shared-class.js");
+const require_lib_exports_helper = require("./exports-helper.js");
+const require_phases = require("../phases.js");
+require("./rest-adapter.js");
+//#region src/lib/remote-objects.ts
+var require_remote_objects = /* @__PURE__ */ require_runtime.__commonJSMin(((exports, module) => {
+	const g = require_lib_messages;
+	/*!
+	* Expose `RemoteObjects`.
+	*/
+	module.exports = RemoteObjects;
+	/*!
+	* Module dependencies.
+	*/
+	const EventEmitter = require("eventemitter2").EventEmitter2;
+	const debug = require("debug")("strong-remoting:remotes");
+	const deprecated = require_lib_deprecate("strong-remoting");
+	const inherits = require("util").inherits;
+	const assert = require("assert");
+	const SharedClass = require_lib_shared_class;
+	const ExportsHelper = require_lib_exports_helper;
+	const PhaseList = (require_phases.init_phases(), require_runtime.__toCommonJS(require_phases.phases_exports)).PhaseList;
+	const TypeRegistry = require_lib_type_registry;
+	/**
+	* Create a new `RemoteObjects` with the given `options`.
+	*
+	* ```js
+	* var remoteObjects = require('strong-remoting').create();
+	* ```
+	*
+	* @param {Object} options
+	* @return {RemoteObjects}
+	* @class
+	* @property {Object} auth Authentication options used by underlying adapters
+	* to set authorization metadata. **The `rest` adapter supports:**
+	*
+	*  - **basic** - `username` and `password` are required.
+	*  - **digest** - `username` and `password` required and `sendImmediately` must
+	* be false.
+	*  - **bearer** - `bearer` must be set as the bearer token
+	*
+	* @property {String} auth.username
+	* @property {String} auth.password
+	* @property {String} auth.bearer The **bearer token**.
+	* @property {Boolean} auth.sendImmediately Defaults to `false`.
+	*/
+	function RemoteObjects(options) {
+		EventEmitter.call(this, { wildcard: true });
+		this.setMaxListeners(16);
+		this.options = options || {};
+		this.exports = this.options.exports || {};
+		this._typeRegistry = new TypeRegistry(this.options.types);
+		this._classes = {};
+		this._setupPhases();
+	}
+	/*!
+	* Inherit from `EventEmitter`.
+	*/
+	inherits(RemoteObjects, EventEmitter);
+	/*!
+	* Simplified APIs
+	*/
+	RemoteObjects.create = function(options) {
+		return new RemoteObjects(options);
+	};
+	RemoteObjects.extend = function(exports$1) {
+		return new ExportsHelper(exports$1);
+	};
+	/**
+	* Create a handler from the given adapter.
+	*
+	* @param {String} nameOrClass Adapter name or provided adapter class
+	* @param {Object} options Adapter options
+	* @return {Function}
+	*/
+	RemoteObjects.prototype.handler = function(nameOrClass, options) {
+		const adapter = new (this.adapter(nameOrClass))(this, options);
+		const handler = adapter.createHandler();
+		if (handler) handler.adapter = adapter;
+		return handler;
+	};
+	/**
+	* Create a connection to a remoting server.
+	*
+	* @param {String} url Server root
+	* @param {String} name Name of the adapter (eg. "rest")
+	*/
+	RemoteObjects.prototype.connect = function(url, name) {
+		let urlWithoutAuth = url;
+		let auth;
+		const parsedUrl = URL.canParse(url) ? new URL(url) : null;
+		if (parsedUrl && (parsedUrl.username || parsedUrl.password)) {
+			auth = this.auth = {};
+			auth.username = parsedUrl.username;
+			auth.password = parsedUrl.password;
+			parsedUrl.username = "";
+			parsedUrl.password = "";
+			urlWithoutAuth = parsedUrl.toString();
+			if (url[url.length - 1] !== urlWithoutAuth[urlWithoutAuth.length - 1]) urlWithoutAuth = urlWithoutAuth.slice(0, -1);
+		}
+		const adapter = new (this.adapter(name))(this);
+		this.serverAdapter = adapter;
+		return adapter.connect(urlWithoutAuth);
+	};
+	/**
+	* Invoke a method on a remote server using the connected adapter.
+	*
+	* @param {String} method The remote method string
+	* @param {String} [ctorArgs] Constructor arguments (for prototype methods)
+	* @param {String} [args] Method arguments
+	* @callback {Function} [callback] callback
+	* @param {Error} err
+	* @param {Any} arg...
+	* @end
+	*/
+	RemoteObjects.prototype.invoke = function(method, ctorArgs, args, callback) {
+		assert(this.serverAdapter, g.f("Cannot invoke method without an adapter. See {{RemoteObjects#connect().}}"));
+		return this.serverAdapter.invoke.apply(this.serverAdapter, arguments, callback);
+	};
+	/**
+	* Get an adapter by name.
+	* @param {String} nameOrClass The adapter name or provided class
+	* @return {Adapter}
+	*/
+	RemoteObjects.prototype.adapter = function(nameOrClass) {
+		if (typeof nameOrClass === "function") {
+			this.validateAdapter(nameOrClass);
+			return nameOrClass;
+		} else {
+			const adapterModulePath = "./" + nameOrClass + "-adapter.js";
+			try {
+				return require(adapterModulePath);
+			} catch (error) {
+				if (!error || error.code !== "MODULE_NOT_FOUND" || !String(error.message || "").includes(adapterModulePath)) throw error;
+				return require("./" + nameOrClass + "-adapter");
+			}
+		}
+	};
+	RemoteObjects.prototype.getRequiredAdapterMethods = () => ["createHandler"];
+	RemoteObjects.prototype.validateAdapter = function(Adapter) {
+		const notImplementedMethods = this.getRequiredAdapterMethods().filter((methodString) => typeof Adapter.prototype[methodString] !== "function");
+		if (notImplementedMethods.length > 0) throw new Error(g.f("Invalid adapter class. The provided adapter class does not implement the following required methods: %s", notImplementedMethods.join(", ")));
+		return Adapter;
+	};
+	/**
+	* Get all classes.
+	*/
+	RemoteObjects.prototype.classes = function(options) {
+		options = options || {};
+		const exports$2 = this.exports;
+		const result = [];
+		const sharedClasses = this._classes;
+		const exportNames = Object.keys(exports$2);
+		const sharedClassNames = Object.keys(sharedClasses);
+		for (let i = 0; i < exportNames.length; i++) {
+			const name = exportNames[i];
+			result.push(new SharedClass(name, exports$2[name], options));
+		}
+		for (let i = 0; i < sharedClassNames.length; i++) result.push(sharedClasses[sharedClassNames[i]]);
+		return result;
+	};
+	/**
+	* Add a shared class.
+	*
+	* @param {SharedClass} sharedClass
+	*/
+	RemoteObjects.prototype.addClass = function(sharedClass) {
+		assert(sharedClass && sharedClass.constructor.name === "SharedClass", g.f("must provide a valid {{SharedClass}}"));
+		this._classes[sharedClass.name] = sharedClass;
+	};
+	/**
+	* Remove a previously-registered shared class.
+	*
+	* @param {string} className The name of the shared class to remove.
+	*/
+	RemoteObjects.prototype.deleteClassByName = function(className) {
+		delete this._classes[className];
+		Object.keys(this.listenerTree).forEach((hooktype) => {
+			delete this.listenerTree[hooktype][className];
+		});
+	};
+	/**
+	* Find a method by its string name.
+	*
+	* @param {String} methodString String specifying the method. For example:
+	*
+	*  - `MyClass.prototype.myMethod`
+	*  - `MyClass.staticMethod`
+	*  - `obj.method`
+	*/
+	RemoteObjects.prototype.findMethod = function(methodString) {
+		const classes = this.classes();
+		for (let i = 0; i < classes.length; i++) {
+			const methods = classes[i].methods();
+			for (let j = 0; j < methods.length; j++) if (methods[j].stringName === methodString) return methods[j];
+		}
+	};
+	/**
+	* List all methods.
+	*/
+	RemoteObjects.prototype.methods = function() {
+		const methods = [];
+		const classes = this.classes();
+		for (let i = 0; i < classes.length; i++) {
+			const classMethods = classes[i].methods();
+			for (let j = 0; j < classMethods.length; j++) methods.push(classMethods[j]);
+		}
+		return methods;
+	};
+	/**
+	* Get as JSON.
+	*/
+	RemoteObjects.prototype.toJSON = function() {
+		const result = {};
+		const methods = this.methods();
+		for (let i = 0; i < methods.length; i++) {
+			const sharedMethod = methods[i];
+			result[sharedMethod.stringName] = {
+				http: sharedMethod.fn && sharedMethod.fn.http,
+				accepts: sharedMethod.accepts,
+				returns: sharedMethod.returns,
+				errors: sharedMethod.errors
+			};
+		}
+		return result;
+	};
+	/**
+	* Execute the given function before the matched method string.
+	*
+	* @example
+	*
+	* Do something before the `user.greet` method is called:
+	* ```js
+	* remotes.before('user.greet', function(ctx, next) {
+	*   if ((ctx.req.param('password') || '').toString() !== '1234') {
+	*     next(new Error('Bad password!'));
+	*   } else {
+	*     next();
+	*   }
+	* });
+	* ```
+	*
+	* Do something before any `user` method:
+	* ```js
+	* remotes.before('user.*', function(ctx, next) {
+	*   console.log('Calling a user method.');
+	*   next();
+	* });
+	* ```
+	*
+	* Do something before a `dog` instance method:
+	* ```js
+	* remotes.before('dog.prototype.*', function(ctx, next) {
+	*   var dog = this;
+	*   console.log('Calling a method on "%s".', dog.name);
+	*   next();
+	* });
+	* ```
+	*
+	* @param {String} methodMatch The glob to match a method string
+	* @callback {Function} hook
+	* @param {Context} ctx The adapter specific context
+	* @param {Function} next Call with an optional error object
+	* @param {SharedMethod} method The SharedMethod object
+	*/
+	RemoteObjects.prototype.before = function(methodMatch, fn) {
+		this.on("before." + methodMatch, fn);
+	};
+	/**
+	* Execute the given `hook` function after the matched method string.
+	*
+	* @example
+	*
+	* Do something after the `speak` instance method.
+	* NOTE: you cannot cancel a method after it has been called.
+	* ```js
+	* remotes.after('dog.prototype.speak', function(ctx, next) {
+	*   console.log('After speak!');
+	*   next();
+	* });
+	*```
+	*
+	* Do something before all methods.
+	```js
+	* remotes.before('**', function(ctx, next, method) {
+	*   console.log('Calling:', method.name);
+	*   next();
+	* });
+	* ```
+	*
+	* Modify all returned values named `result`.
+	* ```js
+	* remotes.after('**', function(ctx, next) {
+	*   ctx.result += '!!!';
+	*   next();
+	* });
+	* ```
+	*
+	* @param {String} methodMatch The glob to match a method string
+	* @callback {Function} hook
+	* @param {Context} ctx The adapter specific context
+	* @param {Function} next Call with an optional error object
+	* @param {SharedMethod} method The SharedMethod object
+	*/
+	RemoteObjects.prototype.after = function(methodMatch, fn) {
+		this.on("after." + methodMatch, fn);
+	};
+	/**
+	* Execute the given `hook` function after the method matched by the method
+	* string failed.
+	*
+	* @example
+	* Do something after the `speak` instance method failed.
+	*
+	* ```js
+	* remotes.afterError('dog.prototype.speak', function(ctx, next) {
+	*   console.log('Cannot speak!', ctx.error);
+	*   next();
+	* });
+	* ```
+	*
+	* Do something before all methods:
+	* ```js
+	* remotes.afterError('**', function(ctx, next, method) {
+	*   console.log('Failed', method.name, ctx.error);
+	*   next();
+	* });
+	* ```
+	*
+	* Modify all returned errors:
+	* ```js
+	* remotes.after('**', function(ctx, next) {
+	*   if (!ctx.error.details) ctx.result.details = {};
+	*   ctx.error.details.info = 'intercepted by a hook';
+	*   next();
+	* });
+	* ```
+	*
+	* Report a different error:
+	* ```js
+	* remotes.after('dog.prototype.speak', function(ctx, next) {
+	*   console.error(ctx.error);
+	*   next(new Error('See server console log for details.'));
+	* });
+	* ```
+	*
+	* @param {String} methodMatch The glob to match a method string
+	* @callback {Function} hook
+	* @param {Context} ctx The adapter specific context
+	* @param {Function} next Call with an optional error object
+	* @param {SharedMethod} method The SharedMethod object
+	*/
+	RemoteObjects.prototype.afterError = function(methodMatch, fn) {
+		this.on("afterError." + methodMatch, fn);
+	};
+	RemoteObjects.prototype.registerPhaseHandler = function(phaseName, methodNameWildcard, handler) {
+		const pattern = methodNameWildcard.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/(^|\.)\*($|\.)/g, "$1[^.]*$2").replace(/(^|\.)\*\*($|\.)/g, "$1.*$2");
+		const matcher = new RegExp("^" + pattern + "$");
+		debug("registerPhaseHandler(%j) -> pattern %j", methodNameWildcard, pattern);
+		this.phases.registerHandler(phaseName, function matchHandler(ctx, next) {
+			if (matcher.test(ctx.method.stringName)) handler(ctx, next);
+			else next();
+		});
+	};
+	/*!
+	* Create a middleware style emit that supports wildcards.
+	*/
+	RemoteObjects.prototype.execHooks = function(when, method, scope, ctx, next) {
+		let stack;
+		let stackIndex = 0;
+		let stackLength = 0;
+		const isStatic = method.isStatic || method.sharedMethod && method.sharedMethod.isStatic;
+		let type, handler;
+		this.objectName = method.sharedClass && method.sharedClass.name || method.restClass && method.restClass.name;
+		this.methodName = method.name;
+		if (method.fullName) type = when + "." + method.fullName;
+		else type = when + "." + this.objectName + (isStatic ? "." : ".prototype.") + this.methodName;
+		if (this.wildcard) {
+			stack = [];
+			const ns = typeof type === "string" ? type.split(this.delimiter) : type.slice();
+			searchListenerTree.call(this, stack, ns, this.listenerTree, 0);
+		} else {
+			handler = this._events[type];
+			if (typeof handler === "function") {
+				this.event = type;
+				stack = [handler];
+			} else if (handler) stack = handler;
+			else return next();
+		}
+		stackLength = stack.length;
+		if (stackLength === 0) return next();
+		function execStack(err) {
+			if (err) return next(err);
+			if (stackIndex >= stackLength) {
+				next();
+				return;
+			}
+			const cur = stack[stackIndex++];
+			if (!cur) {
+				execStack();
+				return;
+			}
+			let hookCompleted = false;
+			try {
+				const advance = function(advanceErr) {
+					if (hookCompleted) return;
+					hookCompleted = true;
+					execStack(advanceErr);
+				};
+				const result = cur.call(scope, ctx, advance, method);
+				if (result && typeof result.then === "function") result.then(function() {
+					advance();
+				}, function(promiseErr) {
+					advance(promiseErr);
+				});
+			} catch (err) {
+				if (!hookCompleted) next(err);
+			}
+		}
+		return execStack();
+	};
+	function searchListenerTree(handlers, type, tree, i) {
+		if (!tree) return;
+		let leaf, len, branch, isolatedBranch, endReached;
+		const typeLength = type.length;
+		const currentType = type[i];
+		const nextType = type[i + 1];
+		if (i === typeLength && tree._listeners) if (typeof tree._listeners === "function") {
+			if (handlers) handlers.push(tree._listeners);
+			return;
+		} else {
+			for (leaf = 0, len = tree._listeners.length; leaf < len; leaf++) if (handlers) handlers.push(tree._listeners[leaf]);
+			return;
+		}
+		if (currentType === "*" || currentType === "**" || tree[currentType]) {
+			if (currentType === "*") {
+				for (branch in tree) if (branch !== "_listeners" && Object.prototype.hasOwnProperty.call(tree, branch)) searchListenerTree(handlers, type, tree[branch], i + 1);
+				return;
+			} else if (currentType === "**") {
+				endReached = i + 1 === typeLength || i + 2 === typeLength && nextType === "*";
+				if (endReached && tree._listeners) searchListenerTree(handlers, type, tree, typeLength);
+				for (branch in tree) if (branch !== "_listeners" && Object.prototype.hasOwnProperty.call(tree, branch)) if (branch === "*" || branch === "**") {
+					if (tree[branch]._listeners && !endReached) searchListenerTree(handlers, type, tree[branch], typeLength);
+					searchListenerTree(handlers, type, tree[branch], i);
+				} else if (branch === nextType) searchListenerTree(handlers, type, tree[branch], i + 2);
+				else searchListenerTree(handlers, type, tree[branch], i);
+				return;
+			}
+			searchListenerTree(handlers, type, tree[currentType], i + 1);
+		}
+		const xTree = tree["*"];
+		if (xTree) searchListenerTree(handlers, type, xTree, i + 1);
+		const xxTree = tree["**"];
+		if (xxTree) {
+			if (i < typeLength) {
+				if (xxTree._listeners) searchListenerTree(handlers, type, xxTree, typeLength);
+				for (branch in xxTree) if (branch !== "_listeners" && Object.prototype.hasOwnProperty.call(xxTree, branch)) if (branch === nextType) searchListenerTree(handlers, type, xxTree[branch], i + 2);
+				else if (branch === currentType) searchListenerTree(handlers, type, xxTree[branch], i + 1);
+				else {
+					isolatedBranch = {};
+					isolatedBranch[branch] = xxTree[branch];
+					searchListenerTree(handlers, type, { "**": isolatedBranch }, i + 1);
+				}
+			} else if (xxTree._listeners) searchListenerTree(handlers, type, xxTree, typeLength);
+			else if (xxTree["*"] && xxTree["*"]._listeners) searchListenerTree(handlers, type, xxTree["*"], typeLength);
+		}
+	}
+	RemoteObjects.prototype._executeAuthorizationHook = function(ctx, cb) {
+		if (typeof this.authorization === "function") this.authorization(ctx, cb);
+		else process.nextTick(function() {
+			cb();
+		});
+	};
+	RemoteObjects.prototype._setupPhases = function() {
+		const self = this;
+		self.phases = new PhaseList();
+		const auth = self.phases.add("auth");
+		const invoke = self.phases.add("invoke");
+		auth.use(function phaseAuthorization(ctx, next) {
+			self._executeAuthorizationHook(ctx, next);
+		});
+		invoke.before(function reportSharedCtorError(ctx, next) {
+			next(ctx.sharedCtorError);
+		});
+		invoke.before(function phaseBeforeInvoke(ctx, next) {
+			self.execHooks("before", ctx.method, ctx.getScope(), ctx, next);
+		});
+		invoke.use(function phaseInvoke(ctx, next) {
+			ctx.invoke(ctx.getScope(), ctx.method, function(err, result) {
+				if (!err) ctx.result = result;
+				next(err);
+			});
+		});
+		invoke.after(function phaseAfterInvoke(ctx, next) {
+			self.execHooks("after", ctx.method, ctx.getScope(), ctx, next);
+		});
+	};
+	/**
+	* Invoke the given shared method using the supplied context.
+	* Execute registered before/after hooks.
+	*
+	* @param {Object} ctx
+	* @param {Object} method
+	* @param {function(Error=)} cb
+	*/
+	RemoteObjects.prototype.invokeMethodInContext = function(ctx, method, cb) {
+		const self = this;
+		const scope = ctx.getScope();
+		if (cb === void 0 && typeof method === "function") {
+			cb = method;
+			method = ctx.method;
+		} else {
+			assert.equal(method, ctx.method);
+			deprecated("invokeMethodInContext(ctx, method, cb) is deprecated.Pass the method as ctx.method instead.");
+		}
+		self.phases.run(ctx, function interceptInvocationErrors(err) {
+			if (!err) return cb();
+			ctx.error = err;
+			self.execHooks("afterError", method, scope, ctx, function(hookErr) {
+				cb(hookErr || err);
+			});
+		});
+	};
+	/**
+	* Determine what scope object to use when invoking the given remote method in
+	* the given context.
+	* @private
+	*/
+	RemoteObjects.prototype.getScope = function(ctx, method) {
+		deprecated("remoteObjects.getScope(ctx, method) is deprecated, use ctx.getScope() instead");
+		assert.equal(ctx.method, method);
+		return ctx.getScope();
+	};
+	/**
+	* Define a named type conversion. The conversion is used when a
+	* `SharedMethod` argument defines a type with the given `name`.
+	*
+	* See also `remotes.defineObjectType`.
+	*
+	* @example
+	*
+	* ```js
+	* remotes.defineType('MyType', {
+	*   // Convert the raw "value" coming typically from JSON.
+	*   // Use the remoting context in "ctx" to access the type registry and
+	*   // other request-related information.
+	*   fromTypedValue: function(ctx, value) {
+	*     if (value === undefined || value === null)
+	*       return { value: value };
+	*
+	*     value = new MyType(value);
+	*     var error = this.validate(ctx, value);
+	*     return error ? { error: error } : { value: value };
+	*   },
+	*
+	*   // Apply any coercion needed to convert values coming from
+	*   // string-only sources like HTTP headers and query string.
+	*   //
+	*   // A sloppy value is one of:
+	*   //  - a string
+	*   //  - an array containing sloppy values
+	*   //  - an object where property values are sloppy
+	*   fromSloppyValue: function(ctx, value) {
+	*     var objectConverter = ctx.typeRegistry.getConverter('object');
+	*     var result = objectConverter.fromSloppyString(ctx, value);
+	*     return result.error ? result : this.fromTypedValue(ctx, result.value);
+	*   },
+	*
+	*   // Perform basic validation of the value. Validations are required to be
+	*   // synchronous.
+	*   validate: function(ctx, value) {
+	*     if (value === undefined || value === null)
+	*       return null;
+	*     if (typeof value !== 'object' || !(value instanceof MyType) {
+	*       return new Error('Value is not an instance of MyType.');
+	*     }
+	*     return null;
+	*   },
+	* });
+	* ```
+	*
+	* @param {String} name The type name
+	* @param {Object} converter A converter implementing the following methods:
+	*
+	*   - `fromTypedValue(ctx, value) -> { value } or { error }`
+	*   - `fromSloppyValue(ctx, value) -> { value } or { error }`
+	*   - `validate(ctx, value) -> error or undefined/null`
+	*/
+	RemoteObjects.prototype.defineType = function(name, converter) {
+		if (typeof converter === "function") throw new Error(g.f("%s is no longer supported. Use one of the new APIs instead: %s or %s", "remoteObjects.defineType(name, fn)", "remoteObjects.defineObjectType(name, factoryFn)", "remoteObjects.defineType(name, converter)"));
+		this._typeRegistry.defineType(name, converter);
+	};
+	/**
+	* Define a named type conversion for an object-like type.
+	* The conversion is used when a `SharedMethod` argument
+	* defines a type with the given `name`.
+	*
+	* Under the hood, a converter is created that ensures the input data
+	* is an object (or sloppy value is coerced to an object) and calls
+	* the provided factory function to convert plain data object to
+	* a class instance.
+	*
+	* @example
+	*
+	* ```js
+	* remotes.defineObjectType('MyClass', function(data) {
+	*   return new MyClass(data);
+	* });
+	* ```
+	*
+	* @param {String} name The type name
+	* @param {Function(Object)} factoryFn Factory function creating object
+	*   instance from a plain-data object.
+	*/
+	RemoteObjects.prototype.defineObjectType = function(name, factoryFn) {
+		this._typeRegistry.registerObjectType(name, factoryFn);
+	};
+	/**
+	* Remove a type registered via `defineType` or `defineObjectType`.
+	*
+	* @param {String} name The type name.
+	*/
+	RemoteObjects.prototype.deleteTypeByName = function(name) {
+		delete this._typeRegistry._types[name.toLowerCase()];
+	};
+	RemoteObjects.convert = RemoteObjects.prototype.convert = function(name, fn) {
+		throw new Error(g.f("RemoteObjects.convert(name, fn) is no longer supported. Use remoteObjects.defineType(name, converter) instead."));
+	};
+	RemoteObjects.defineType = function(name, fn) {
+		throw new Error(g.f("RemoteObjects.defineType(name, fn) is no longer supported. Use remoteObjects.defineType(name, converter) instead."));
+	};
+}));
+//#endregion
+module.exports = require_remote_objects();
+
+//# sourceMappingURL=remote-objects.js.map