@open-pioneer/core

This package contains basic utility functions and classes used in Open Pioneer Trails applications.

Usage

Errors

The Error class extends JavaScript's global error class with a user defined id value that can be used to explicitly identify error conditions.

import { Error } from "@open-pioneer/core";
throw new Error("my-error:identifier", "This is the error message");

Error also exposes the optional cause attribute that allows nesting of error instances. Note that browser support for that property is still required:

import { Error, getErrorChain } from "@open-pioneer/core";

try {
    someFunctionThatCanThrow();
} catch (e) {
    throw new Error("my-error:higher-level-error-id", "Error text", { cause: e });
}

// getErrorChain gathers the error and all its causes (if any) into an array:
const errors = getErrorChain(error);

Resources

The Resource type exported from this package is used by objects with a destructor. All object needing some cleanup action to be called should use the destroy method for consistency and easier handling.

Logger

The Logger class provides a logger for standardized application wide logging. The log level is configured globally in the file vite.config.ts: to change the application's log level, define the __LOG_LEVEL__ constant to a custom value.

To create a logger instance, call the createLogger method. It takes a prefix (string) to prepend to each message. To encode hierarchical names, use : as a separator (for example "some-package:SomeClass").

The logger provides log methods for the following log levels with the following order: DEBUG < INFO < WARN < ERROR.

For example (as class attribute):

import { createLogger, Logger } from "@open-pioneer/core";

export class LoggerTestExample {
    private logger: Logger;
    constructor() {
        this.logger = createLogger("example-package:LoggerTestExample");
    }

    testMethod() {
        this.logger.warn("example message", { testLog: 123, text: "this is a text" });
    }
}

Or as a shared logger at module scope:

import { createLogger } from "@open-pioneer/core";
const LOG = createLogger("example-package");

With recent version of the trails vite plugin, you can also use this convenient way to create a logger:

import { sourceId } from "open-pioneer:source-info";
// sourceId is an automatic identifier based on the current file.
const LOG = createLogger(sourceId);

Deprecations

The deprecated function can be used to print warnings when a deprecated entity is used. Deprecations are printed (once) during development, and not at all in production. You can disable deprecations via the global configuration in vite.config.ts: set __PRINT_DEPRECATIONS__ to false to hide deprecation messages even during development.

To emit a deprecation warning, create a helper function through the deprecated function. Then, when the deprecated functionality is being used, simply call that helper function:

const printDeprecation = deprecated({
    name: "someFunctionName",
    packageName: "some-package",
    since: "v1.2.3",
    alternative: "use xyz instead"
});

// Later, when the deprecated function is actually being used:
function someFunctionName() {
    printDeprecation(); // prints warning on first call
    // ...
}

Events

Note: the EventEmitter class is deprecated since v4.2.0. Use @conterra/reactivity-events instead.

The package exports the EventEmitter class that supports emitting and subscribing to user defined events.

Equality functions

Use shallowEqual and deepEqual to compare two generic objects. Note that the functions are intended to be used with plain old data (i.e. mostly JSON).

They do not support cycles.

Examples:

import { shallowEqual, deepEqual } from "@open-pioneer/core";

shallowEqual({ a: 1 }, { a: 1 }); // true
shallowEqual({ a: { x: 1 } }, { a: { x: 1 } }); // false
deepEqual({ a: { x: 1 } }, { a: { x: 1 } }); // true
deepEqual([1, [2, 3]], [1, [2, 3]]); // true

License

Apache-2.0 (see LICENSE file)