diff --git a/src/NodeJS/INodeJSService.cs b/src/NodeJS/INodeJSService.cs index 1ac591c..80c1c5f 100644 --- a/src/NodeJS/INodeJSService.cs +++ b/src/NodeJS/INodeJSService.cs @@ -11,74 +11,406 @@ namespace Jering.Javascript.NodeJS public interface INodeJSService : IDisposable { /// - /// Invokes a function exported by a NodeJS module on disk. + /// Invokes a function from the exports of a NodeJS module on disk. + /// Returns a value. /// - /// The type of object this method will return. It can be a JSON-serializable type, , or . - /// The path to the module (i.e., JavaScript file) relative to . - /// The name of the function in the module's exports to be invoked. If unspecified, the module's exports object - /// is assumed to be a function, and is invoked. - /// The sequence of JSON-serializable and/or string arguments to be passed to the function to invoke. + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The path to the module relative to . This value must not be null, whitespace or an empty string. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. /// The cancellation token for the asynchronous operation. /// The task object representing the asynchronous operation. /// Thrown if NodeJS cannot be initialized. /// Thrown if the invocation request times out. /// Thrown if a NodeJS error occurs. - /// Thrown if this instance has been disposed or if an attempt is made to use one of its dependencies that has been disposed. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. /// Thrown if is cancelled. Task InvokeFromFileAsync(string modulePath, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); /// - /// Invokes a function exported by a NodeJS module in string form. + /// Invokes the function exported by a NodeJS module on disk. + /// Returns a value. /// - /// The type of object this method will return. It can be a JSON-serializable type, , or . - /// The module in string form. - /// The module's cache identifier in the NodeJS module cache. If unspecified, the module will not be cached. - /// The name of the function in the module's exports to be invoked. If unspecified, the module's exports object - /// is assumed to be a function, and is invoked. - /// The sequence of JSON-serializable and/or string arguments to be passed to the function to invoke. + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The path to the module relative to . This value must not be null, whitespace or an empty string. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromFileAsync(string modulePath, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module on disk. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The path to the module relative to . This value must not be null, whitespace or an empty string. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromFileAsync(string modulePath, string exportName, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module on disk. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The path to the module relative to . This value must not be null, whitespace or an empty string. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. /// The task object representing the asynchronous operation. /// Thrown if NodeJS cannot be initialized. /// Thrown if the invocation request times out. /// Thrown if a NodeJS error occurs. - /// Thrown if this instance has been disposed or if an attempt is made to use one of its dependencies that has been disposed. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. /// Thrown if is cancelled. - Task InvokeFromStringAsync(string moduleString, string newCacheIdentifier = null, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); + Task InvokeFromFileAsync(string modulePath, string exportName, CancellationToken cancellationToken, params object[] args); /// - /// Invokes a function exported by a NodeJS module in Stream form. + /// Invokes a function from the exports of a NodeJS module on disk. + /// Does not return any value. /// - /// The type of object this method will return. It can be a JSON-serializable type, , or . - /// The module in Stream form. - /// The module's cache identifier in the NodeJS module cache. If unspecified, the module will not be cached. - /// The name of the function in the module's exports to be invoked. If unspecified, the module's exports object - /// is assumed to be a function, and is invoked. - /// The sequence of JSON-serializable and/or string arguments to be passed to the function to invoke. + /// The path to the module relative to . This value must not be null, whitespace or an empty string. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromFileAsync(string modulePath, string exportName, CancellationToken cancellationToken, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in string form. This value must not be null, whitespace or an empty string. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The cancellation token for the asynchronous operation. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStringAsync(string moduleString, string cacheIdentifier = null, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); + + /// + /// Invokes the function exported by a NodeJS module in string form. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in string form. This value must not be null, whitespace or an empty string. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. /// The task object representing the asynchronous operation. /// Thrown if NodeJS cannot be initialized. /// Thrown if the invocation request times out. /// Thrown if a NodeJS error occurs. - /// Thrown if this instance has been disposed or if an attempt is made to use one of its dependencies that has been disposed. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStringAsync(string moduleString, params object[] args); + + /// + /// Invokes the function exported by a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in string form. This value must not be null, whitespace or an empty string. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStringAsync(string moduleString, string cacheIdentifier, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in string form. This value must not be null, whitespace or an empty string. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStringAsync(string moduleString, string cacheIdentifier, string exportName, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in string form. This value must not be null, whitespace or an empty string. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStringAsync(string moduleString, string cacheIdentifier, string exportName, CancellationToken cancellationToken, params object[] args); + + /// + /// Invokes the function exported by a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, generates the module using a factory, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The factory that generates the module. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStringAsync(Func moduleFactory, string cacheIdentifier, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, generates the module using a factory, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The factory that generates the module. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStringAsync(Func moduleFactory, string cacheIdentifier, string exportName, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, generates the module using a factory, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The factory that generates the module. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStringAsync(Func moduleFactory, string cacheIdentifier, string exportName, CancellationToken cancellationToken, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in string form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Does not return any value. + /// + /// The module in string form. This value must not be null, whitespace or an empty string. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStringAsync(string moduleString, string cacheIdentifier, string exportName, CancellationToken cancellationToken, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in stream form. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The cancellation token for the asynchronous operation. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStreamAsync(Stream moduleStream, string cacheIdentifier = null, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); + + /// + /// Invokes the function exported by a NodeJS module in stream form. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in stream form. This value must not be null. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStreamAsync(Stream moduleStream, params object[] args); + + /// + /// Invokes the function exported by a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in stream form. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStreamAsync(Stream moduleStream, string cacheIdentifier, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in stream form. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStreamAsync(Stream moduleStream, string cacheIdentifier, string exportName, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The module in stream form. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStreamAsync(Stream moduleStream, string cacheIdentifier, string exportName, CancellationToken cancellationToken, params object[] args); + + /// + /// Invokes the function exported by a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, generates the module using a factory, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The factory that generates the module. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStreamAsync(Func moduleFactory, string cacheIdentifier, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, generates the module using a factory, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The factory that generates the module. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + Task InvokeFromStreamAsync(Func moduleFactory, string cacheIdentifier, string exportName, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, generates the module using a factory, compiles the module and caches its exports. + /// Returns a value. + /// + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The factory that generates the module. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// The task object representing the asynchronous operation. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. + /// Thrown if is cancelled. + Task InvokeFromStreamAsync(Func moduleFactory, string cacheIdentifier, string exportName, CancellationToken cancellationToken, params object[] args); + + /// + /// Invokes a function from the exports of a NodeJS module in stream form. + /// If the module's exports exists in the cache, retrieves it from there. Otherwise, compiles the module and caches its exports. + /// Does not return any value. + /// + /// The module in stream form. This value must not be null. + /// The module's cache identifier. If this value is null, no attempt is made to retrieve or cache the module's exports. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The cancellation token for the asynchronous operation. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. + /// Thrown if NodeJS cannot be initialized. + /// Thrown if the invocation request times out. + /// Thrown if a NodeJS error occurs. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. /// Thrown if is cancelled. - Task InvokeFromStreamAsync(Stream moduleStream, string newCacheIdentifier = null, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); + Task InvokeFromStreamAsync(Stream moduleStream, string cacheIdentifier, string exportName, CancellationToken cancellationToken, params object[] args); /// - /// Attempts to invoke a function exported by a NodeJS module cached by NodeJS. + /// Attempts to invoke a function from the exports of a NodeJS module cached by NodeJS. /// - /// The type of object this method will return. It can be a JSON-serializable type, , or . - /// The cache identifier of the module. - /// The name of the function in the module's exports to be invoked. If unspecified, the module's exports object - /// is assumed to be a function, and is invoked. - /// The sequence of JSON-serializable and/or string arguments to be passed to the function to invoke. + /// The type this method returns. This may be any JSON-serializable type, , or . + /// The cache identifier of the module. + /// The name of the function in the module's exports to invoke. If this value is null, the module's exports is assumed to be a function and is invoked. + /// The sequence of JSON-serializable arguments to pass to the function to invoke. /// The cancellation token for the asynchronous operation. /// The task object representing the asynchronous operation. On completion, the task returns a (bool, T) with the bool set to true on /// success and false otherwise. /// Thrown if NodeJS cannot be initialized. /// Thrown if the invocation request times out. /// Thrown if a NodeJS error occurs. - /// Thrown if this instance has been disposed or if an attempt is made to use one of its dependencies that has been disposed. + /// Thrown if this instance is disposed or if an attempt is made to use one of its dependencies that is disposed. /// Thrown if is cancelled. - Task<(bool, T)> TryInvokeFromCacheAsync(string moduleCacheIdentifier, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); + Task<(bool, T)> TryInvokeFromCacheAsync(string cacheIdentifier, string exportName = null, object[] args = null, CancellationToken cancellationToken = default); } }