# @open-pioneer/core

> Contains basic utility functions and classes used by the @open-pioneer project.

Latest version **4.10.0** (published 2026-11-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @open-pioneer/core
pnpm add @open-pioneer/core
yarn add @open-pioneer/core
bun add @open-pioneer/core
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 4.10.0 |
| Published | 2026-11-19 |
| First published | 2023-06-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 73.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Maintainers | mbeckem_conterra, jessebluemr, antoniave_conterra, open_pioneer |
| Keywords | open-pioneer-trails |

## Links

- npm: https://www.npmjs.com/package/@open-pioneer/core
- Repository: https://github.com/open-pioneer/trails-core-packages
- Homepage: https://github.com/open-pioneer
- npm.io page: https://npm.io/package/@open-pioneer/core

## Dependencies (2)

- [fast-equals](https://npm.io/package/fast-equals.md) ^6.2.2
- [@conterra/reactivity-events](https://npm.io/package/@conterra/reactivity-events.md) ^0.8.9

## Recent versions

- 4.10.0 (latest) — 2026-11-19
- 4.10.0-dev.20261119090001 (dev) — 2026-11-19
- 4.7.1-dev-test-snapshot-123.20260821142246 (dev-test-snapshot-123) — 2026-08-21
- 4.7.1-dev-test-snapshot.20260821120534 (dev-test-snapshot) — 2026-08-21
- 4.9.0 — 2026-10-30
- 4.9.0-dev.20261029090037 — 2026-10-29
- 4.9.0-dev.20261002130116 — 2026-10-02
- 4.9.0-dev.20260930055642 — 2026-09-30
- 4.8.0 — 2026-09-17
- 4.8.0-dev.20260910101405 — 2026-09-10
- 4.7.0 — 2026-07-28
- 4.7.0-dev.20260727091735 — 2026-07-27
- 4.7.0-dev.20260713101438 — 2026-07-13
- 4.7.0-dev-test-snapshot.20260707113553 — 2026-07-07
- 4.7.0-dev-test-snapshot.20260707113111 — 2026-07-07
- … 91 more at https://npm.io/package/@open-pioneer/core/versions

## README

# @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.

```js
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:

```js
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` interface 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` function.
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):

```ts
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:

```ts
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:

```ts
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:

```ts
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](https://www.npmjs.com/package/@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:

```ts
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)

---
_Source: https://npm.io/package/@open-pioneer/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
