@lumino/coreutils
- Version 2.2.0
- Published
- 562 kB
- 1 dependency
- BSD-3-Clause license
Install
npm i @lumino/coreutils
yarn add @lumino/coreutils
pnpm add @lumino/coreutils
Overview
coreutils
Index
Classes
Interfaces
Type Aliases
Namespaces
Classes
class MimeData
class MimeData {}
An object which stores MIME data for general application use.
#### Notes This class does not attempt to enforce "correctness" of MIME types and their associated data. Since this class is designed to transfer arbitrary data and objects within the same application, it assumes that the user provides correct and accurate data.
method clear
clear: () => void;
Remove all data entries from the dataset.
method clearData
clearData: (mime: string) => void;
Remove the data entry for the given MIME type.
Parameter mime
The MIME type of interest.
#### Notes This is a no-op if there is no entry for the given MIME type.
method getData
getData: (mime: string) => any | undefined;
Get the data value for the given MIME type.
Parameter mime
The MIME type of interest.
Returns
The value for the given MIME type, or
undefined
if the dataset does not contain a value for the type.
method hasData
hasData: (mime: string) => boolean;
Test whether the dataset has an entry for the given type.
Parameter mime
The MIME type of interest.
Returns
true
if the dataset contains a value for the given MIME type,false
otherwise.
method setData
setData: (mime: string, data: unknown) => void;
Set the data value for the given MIME type.
Parameter mime
The MIME type of interest.
Parameter data
The data value for the given MIME type.
#### Notes This will overwrite any previous entry for the MIME type.
method types
types: () => string[];
Get an array of the MIME types contained within the dataset.
Returns
A new array of the MIME types, in order of insertion.
class PluginRegistry
class PluginRegistry<T = any> {}
Plugin registry.
constructor
constructor(options?: PluginRegistry.IOptions);
property application
application: {};
The application object.
It will be provided as first argument to the plugins activation and deactivation functions.
It can only be set once.
By default, it is
null
.
property deferredPlugins
readonly deferredPlugins: string[];
The list of all the deferred plugins.
method activatePlugin
activatePlugin: (id: string) => Promise<void>;
Activate the plugin with the given ID.
Parameter id
The ID of the plugin of interest.
Returns
A promise which resolves when the plugin is activated or rejects with an error if it cannot be activated.
method activatePlugins
activatePlugins: ( kind: 'startUp' | 'defer', options?: PluginRegistry.IStartOptions) => Promise<void>;
Activate all the deferred plugins.
Returns
A promise which will resolve when each plugin is activated or rejects with an error if one cannot be activated.
method deactivatePlugin
deactivatePlugin: (id: string) => Promise<string[]>;
Deactivate the plugin and its downstream dependents if and only if the plugin and its dependents all support
deactivate
.Parameter id
The ID of the plugin of interest.
Returns
A list of IDs of downstream plugins deactivated with this one.
method deregisterPlugin
deregisterPlugin: (id: string, force?: boolean) => void;
Deregister a plugin with the application.
Parameter id
The ID of the plugin of interest.
Parameter force
Whether to deregister the plugin even if it is active.
method getPluginDescription
getPluginDescription: (id: string) => string;
Get a plugin description.
Parameter id
The ID of the plugin of interest.
Returns
The plugin description.
method hasPlugin
hasPlugin: (id: string) => boolean;
Test whether a plugin is registered with the application.
Parameter id
The ID of the plugin of interest.
Returns
true
if the plugin is registered,false
otherwise.
method isPluginActivated
isPluginActivated: (id: string) => boolean;
Test whether a plugin is activated with the application.
Parameter id
The ID of the plugin of interest.
Returns
true
if the plugin is activated,false
otherwise.
method listPlugins
listPlugins: () => string[];
List the IDs of the plugins registered with the application.
Returns
A new array of the registered plugin IDs.
method registerPlugin
registerPlugin: (plugin: IPlugin<T, any>) => void;
Register a plugin with the application.
Parameter plugin
The plugin to register.
#### Notes An error will be thrown if a plugin with the same ID is already registered, or if the plugin has a circular dependency.
If the plugin provides a service which has already been provided by another plugin, the new service will override the old service.
method registerPlugins
registerPlugins: (plugins: IPlugin<T, any>[]) => void;
Register multiple plugins with the application.
Parameter plugins
The plugins to register.
#### Notes This calls
registerPlugin()
for each of the given plugins.
method resolveOptionalService
resolveOptionalService: <U>(token: Token<U>) => Promise<U | null>;
Resolve an optional service of a given type.
Parameter token
The token for the service type of interest.
Returns
A promise which resolves to an instance of the requested service, or
null
if it cannot be resolved.#### Notes Services are singletons. The same instance will be returned each time a given service token is resolved.
If the plugin which provides the service has not been activated, resolving the service will automatically activate the plugin.
User code will not typically call this method directly. Instead, the optional services for the user's plugins will be resolved automatically when the plugin is activated.
method resolveRequiredService
resolveRequiredService: <U>(token: Token<U>) => Promise<U>;
Resolve a required service of a given type.
Parameter token
The token for the service type of interest.
Returns
A promise which resolves to an instance of the requested service, or rejects with an error if it cannot be resolved.
#### Notes Services are singletons. The same instance will be returned each time a given service token is resolved.
If the plugin which provides the service has not been activated, resolving the service will automatically activate the plugin.
User code will not typically call this method directly. Instead, the required services for the user's plugins will be resolved automatically when the plugin is activated.
class PromiseDelegate
class PromiseDelegate<T> {}
A class which wraps a promise into a delegate object.
#### Notes This class is useful when the logic to resolve or reject a promise cannot be defined at the point where the promise is created.
constructor
constructor();
Construct a new promise delegate.
property promise
readonly promise: Promise<T>;
The promise wrapped by the delegate.
method reject
reject: (reason: unknown) => void;
Reject the wrapped promise with the given value.
- The reason for rejecting the promise.
method resolve
resolve: (value: T | PromiseLike<T>) => void;
Resolve the wrapped promise with the given value.
Parameter value
The value to use for resolving the promise.
class Token
class Token<T> {}
A runtime object which captures compile-time type information.
#### Notes A token captures the compile-time type of an interface or class in an object which can be used at runtime in a type-safe fashion.
constructor
constructor(name: string, description?: string);
Construct a new token.
Parameter name
A human readable name for the token.
Parameter description
Token purpose description for documentation.
property description
readonly description?: string;
Token purpose description.
property name
readonly name: string;
The human readable name for the token.
#### Notes This can be useful for debugging and logging.
Interfaces
interface IPlugin
interface IPlugin<T, U> {}
A user-defined application plugin.
property activate
activate: (app: T, ...args: any[]) => U | Promise<U>;
A function invoked to activate the plugin.
Parameter app
The application provided by PluginRegistry.application .
Parameter args
The services specified by the
requires
property.Returns
The provided service, or a promise to the service.
#### Notes This function will be called whenever the plugin is manually activated, or when another plugin being activated requires the service it provides.
This function will not be called unless all of its required services can be fulfilled.
property autoStart
autoStart?: boolean | 'defer';
Whether the plugin should be activated on application start or waiting for being required. If the value is 'defer' then the plugin should be activated only after the application is started.
#### Notes The default is
false
.
property deactivate
deactivate?: ((app: T, ...args: any[]) => void | Promise<void>) | null;
A function invoked to deactivate the plugin.
Parameter app
The application PluginRegistry.application .
Parameter args
The services specified by the
requires
property.
property description
description?: string;
Plugin description.
#### Notes This can be used to provide user documentation on the feature brought by a plugin.
property id
id: string;
The human readable ID of the plugin.
#### Notes This must be unique within an application.
property optional
optional?: Token<any>[];
The types of optional services for the plugin, if any.
#### Notes These tokens correspond to the services that can be used by the plugin if available, but are not necessarily required.
The optional services will be passed to the
activate()
function following all required services. If an optional service cannot be resolved,null
will be passed in its place.
property provides
provides?: Token<U> | null;
The type of service provided by the plugin, if any.
#### Notes This token corresponds to the service exported by the plugin.
When the plugin is activated, the return value of
activate()
is used as the concrete instance of the type.
property requires
requires?: Token<any>[];
The types of required services for the plugin, if any.
#### Notes These tokens correspond to the services that are required by the plugin for correct operation.
When the plugin is activated, a concrete instance of each type will be passed to the
activate()
function, in the order they are specified in therequires
array.
interface JSONArray
interface JSONArray extends Array<JSONValue> {}
A type definition for a JSON array.
interface JSONObject
interface JSONObject {}
A type definition for a JSON object.
index signature
[key: string]: JSONValue;
interface PartialJSONArray
interface PartialJSONArray extends Array<PartialJSONValue> {}
A type definition for a partial JSON array.
Note: Partial here means that JSON object attributes can be
undefined
.
interface PartialJSONObject
interface PartialJSONObject {}
A type definition for a partial JSON object.
Note: Partial here means that the JSON object attributes can be
undefined
.
index signature
[key: string]: PartialJSONValue | undefined;
interface ReadonlyJSONArray
interface ReadonlyJSONArray extends ReadonlyArray<ReadonlyJSONValue> {}
A type definition for a readonly JSON array.
interface ReadonlyJSONObject
interface ReadonlyJSONObject {}
A type definition for a readonly JSON object.
index signature
readonly [key: string]: ReadonlyJSONValue;
interface ReadonlyPartialJSONArray
interface ReadonlyPartialJSONArray extends ReadonlyArray<ReadonlyPartialJSONValue> {}
A type definition for a readonly partial JSON array.
Note: Partial here means that JSON object attributes can be
undefined
.
interface ReadonlyPartialJSONObject
interface ReadonlyPartialJSONObject {}
A type definition for a readonly partial JSON object.
Note: Partial here means that JSON object attributes can be
undefined
.
index signature
readonly [key: string]: ReadonlyPartialJSONValue | undefined;
Type Aliases
type JSONPrimitive
type JSONPrimitive = boolean | number | string | null;
A type alias for a JSON primitive.
type JSONValue
type JSONValue = JSONPrimitive | JSONObject | JSONArray;
A type alias for a JSON value.
type PartialJSONValue
type PartialJSONValue = JSONPrimitive | PartialJSONObject | PartialJSONArray;
A type alias for a partial JSON value.
Note: Partial here means that JSON object attributes can be
undefined
.
type ReadonlyJSONValue
type ReadonlyJSONValue = JSONPrimitive | ReadonlyJSONObject | ReadonlyJSONArray;
A type alias for a readonly JSON value.
type ReadonlyPartialJSONValue
type ReadonlyPartialJSONValue = | JSONPrimitive | ReadonlyPartialJSONObject | ReadonlyPartialJSONArray;
A type alias for a readonly partial JSON value.
Note: Partial here means that JSON object attributes can be
undefined
.
Namespaces
namespace JSONExt
namespace JSONExt {}
The namespace for JSON-specific functions.
variable emptyArray
const emptyArray: ReadonlyJSONArray;
A shared frozen empty JSONArray
variable emptyObject
const emptyObject: ReadonlyJSONObject;
A shared frozen empty JSONObject
function deepCopy
deepCopy: <T extends ReadonlyPartialJSONValue>(value: T) => T;
Create a deep copy of a JSON value.
Parameter value
The JSON value to copy.
Returns
A deep copy of the given JSON value.
function deepEqual
deepEqual: ( first: ReadonlyPartialJSONValue, second: ReadonlyPartialJSONValue) => boolean;
Compare two JSON values for deep equality.
Parameter first
The first JSON value of interest.
Parameter second
The second JSON value of interest.
Returns
true
if the values are equivalent,false
otherwise.
function isArray
isArray: { (value: JSONValue): value is JSONArray; (value: ReadonlyJSONValue): value is ReadonlyJSONArray; (value: PartialJSONValue): value is PartialJSONArray; (value: ReadonlyPartialJSONValue): value is ReadonlyPartialJSONArray;};
Test whether a JSON value is an array.
Parameter value
The JSON value of interest.
Returns
true
if the value is a an array,false
otherwise.
function isObject
isObject: { (value: JSONValue): value is JSONObject; (value: ReadonlyJSONValue): value is ReadonlyJSONObject; (value: PartialJSONValue): value is PartialJSONObject; (value: ReadonlyPartialJSONValue): value is ReadonlyPartialJSONObject;};
Test whether a JSON value is an object.
Parameter value
The JSON value of interest.
Returns
true
if the value is a an object,false
otherwise.
function isPrimitive
isPrimitive: (value: ReadonlyPartialJSONValue) => value is JSONPrimitive;
Test whether a JSON value is a primitive.
Parameter value
The JSON value of interest.
Returns
true
if the value is a primitive,false
otherwise.
namespace PluginRegistry
namespace PluginRegistry {}
PluginRegistry namespace
interface IOptions
interface IOptions {}
PluginRegistry constructor options.
property validatePlugin
validatePlugin?: (plugin: IPlugin<any, any>) => boolean;
Validate that a plugin is allowed to be registered.
Default is
() => true
.Parameter plugin
The plugin to validate
Returns
Whether the plugin can be registered or not.
#### Notes We recommend you print a console message with the reason a plugin is invalid.
interface IStartOptions
interface IStartOptions {}
An options object for application startup.
property ignorePlugins
ignorePlugins?: string[];
The plugins to **not** activate on startup.
#### Notes This will override
startPlugins
and anyautoStart
plugins.
property startPlugins
startPlugins?: string[];
The plugins to activate on startup.
#### Notes These will be *in addition* to any
autoStart
plugins.
namespace Random
namespace Random {}
The namespace for random number related functionality.
variable getRandomValues
const getRandomValues: (buffer: Uint8Array) => void;
A function which generates random bytes.
Parameter buffer
The
Uint8Array
to fill with random bytes.#### Notes A cryptographically strong random number generator will be used if available. Otherwise,
Math.random
will be used as a fallback for randomness.The following RNGs are supported, listed in order of precedence: -
window.crypto.getRandomValues
-window.msCrypto.getRandomValues
- `require('crypto').randomFillSync - `require('crypto').randomBytes -Math.random
namespace UUID
namespace UUID {}
The namespace for UUID related functionality.
function uuid4
uuid4: () => string;
A function which generates UUID v4 identifiers.
Returns
A new UUID v4 string.
#### Notes This implementation complies with RFC 4122.
This uses
Random.getRandomValues()
for random bytes, which in turn will use the underlyingcrypto
module of the platform if it is available. The fallback for randomness isMath.random
.
Package Files (8)
Dependencies (1)
Dev Dependencies (18)
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@lumino/coreutils
.
- Markdown[](https://www.jsdocs.io/package/@lumino/coreutils)
- HTML<a href="https://www.jsdocs.io/package/@lumino/coreutils"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 5231 ms. - Missing or incorrect documentation? Open an issue for this package.