@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:

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

npm install @sdux-vault/shared

Usage

Basic Import

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

Example: Utility Usage

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

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

Example: Type Usage

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:

@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

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:

import '@sdux-vault/shared';

Triggers:

• version registration for DevTools

Behavior:

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

Development

Build

npm run build:shared

Output:

dist/shared

Test

npm run test:shared

Verify

npm run verify

Includes:

• linting
• formatting
• type checking
• tests

Publishing

See RELEASE.md for full publishing instructions.

Ecosystem

• @sdux-vault/addons — optional, composable extensions for runtime behavior (README)
• @sdux-vault/core — execution engine for pipelines and state orchestration (README)
• @sdux-vault/core-extensions/angular — Angular integration layer (signals, DI, reactive bindings) (README)
• @sdux-vault/devtools — observability and debugging layer for runtime inspection (README)
• @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