npm package: @sdux-vault/shared
Description: > Core primitives, contracts, and utilities for the SDuX platform.
Latest version: 0.0.12

# @sdux-vault/shared

> Core primitives, contracts, and utilities for the SDuX platform.

`@sdux-vault/shared` is the **foundation of the SDuX ecosystem**.  
It defines the universal language used across all SDuX packages, including types, contracts, behaviors, and utilities.

---

## TL;DR

For full documentation, guides, and API references:  
https://www.sdux-vault.com

---

## Overview

SDuX is built as a layered system:

```plaintext
shared → engine → core → core-extensions → apps
           └─────────---------───────────→ devtools
```

- **apps** → end-user applications
- **core** → behavior runtime + execution layer
- **core-extensions** → framework integrations (Angular, React, etc.)
- **devtools** → end-user tooling
- **engine** → runtime engine and orchestration
- **shared** → contracts, types, utilities (this package)

---

## What This Package Provides

- **Core contracts** — interfaces, shapes, and types
- **Behavior + controller abstractions**
- **Utility functions** — safe, composable, framework-agnostic
- **Configuration primitives**
- **Error models and services**
- **Runtime instrumentation hooks (DevTools integration)**

---

## Key Characteristics

- ✅ Framework-agnostic TypeScript
- ✅ Tree-shakable
- ✅ SSR-safe and browser-safe
- ✅ Designed for composition and extensibility
- ✅ Stable, domain-driven public API

---

## Installation

```bash
npm install @sdux-vault/shared
```

---

## Usage

### Basic Import

```ts
import { VaultError, BehaviorTypes } from '@sdux-vault/shared';
```

---

### Example: Utility Usage

```ts
import { isPromise } from '@sdux-vault/shared';

if (isPromise(value)) {
  // handle async flow
}
```

---

### Example: Type Usage

```ts
import type { BehaviorType } from '@sdux-vault/shared';
```

---

## Public API Structure

### Tree-Shakable by Default

- No unnecessary side effects
- Domain-based exports
- Minimal runtime footprint

---

### Framework-Agnostic Core

This package:

- has zero framework dependencies
- supports multiple adapters
- acts as the foundation for integrations like:

```plaintext
@sdux-vault/core-extensions/*
```

---

### Safe Runtime Instrumentation

Includes dev-only instrumentation:

- version registration
- DevTools integration

These are:

- environment guarded
- idempotent
- safe in SSR and production

---

## Environment Utilities

```ts
import { DevMode } from '@sdux-vault/shared';
import { isTestEnv } from '@sdux-vault/shared';
```

Provides runtime awareness for:

- development mode
- test environments

These are part of the **runtime platform**, not test-only helpers.

---

## Utilities

The `utils` domain includes:

- type guards
- safe helpers
- logging utilities
- runtime helpers

All utilities are:

- side-effect free (except controlled instrumentation)
- safe for universal usage

---

## Side Effects

This package performs **controlled, dev-only side effects**:

```ts
import '@sdux-vault/shared';
```

Triggers:

- version registration for DevTools

Behavior:

- no-op in production
- idempotent
- safe across all runtimes

---

## Development

### Build

```bash
npm run build:shared
```

Output:

```plaintext
dist/shared
```

---

### Test

```bash
npm run test:shared
```

---

### Verify

```bash
npm run verify
```

Includes:

- linting
- formatting
- type checking
- tests

---

## Publishing

See [RELEASE.md](./RELEASE.md) for full publishing instructions.

---

## Ecosystem

- `@sdux-vault/addons` — optional, composable extensions for runtime behavior ([README](../addons/README.md))
- `@sdux-vault/core` — execution engine for pipelines and state orchestration ([README](../core/README.md))
- `@sdux-vault/core-extensions/angular` — Angular integration layer (signals, DI, reactive bindings) ([README](../core-extensions/angular/README.md))
- `@sdux-vault/devtools` — observability and debugging layer for runtime inspection ([README](../devtools/tooling/README.md))
- `@sdux-vault/engine` — orchestration, conductor, decision engine

---

### Tree Shaking & Side Effects

This package includes intentional side effects for:

- global TypeScript typing augmentation
- runtime version registration for devtools

These are required for correct framework behavior.

As a result, the bundle is marked as side-effectful.

---

## License

For full licensing details:  
https://www.sdux-vault.com/docs/welcome/license#license-texts

MIT © SDuX Vault