@sdux-vault/engine 0.0.9

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sdux-vault/engine",
+  "version": "0.0.9",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdux-vault/vault-engine.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://www.sdux-vault.com",
+  "dependencies": {
+    "@sdux-vault/devtools": ">=0.0.6 <0.1.0",
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@sdux-vault/shared": ">=0.0.6 <0.1.0",
+    "rxjs": "^7.0.0"
+  },
+  "files": [
+    "fesm2022/",
+    "types/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "types": "./types/sdux-vault-engine.d.ts",
+  "main": "./fesm2022/sdux-vault-engine.mjs",
+  "sideEffects": [
+    "./fesm2022/*.mjs",
+    "src/version/version.register.ts"
+  ],
+  "module": "fesm2022/sdux-vault-engine.mjs",
+  "typings": "types/sdux-vault-engine.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/sdux-vault-engine.d.ts",
+      "default": "./fesm2022/sdux-vault-engine.mjs"
+    }
+  }
+}

package/types/sdux-vault-engine.d.ts

@@ -0,0 +1,440 @@
+import * as _sdux_vault_shared from '@sdux-vault/shared';
+import { TapCallback, BehaviorClassContract, FeatureCellBaseShape, CoreEmitStateCallback, VaultErrorCallback, FilterFunction, DeferredType, ReducerFunction, InterceptorBehaviorClassContract, OperatorsBehaviorClassContract, ControllerClassContract, ControllerContract, ControllerContext, VaultErrorShape, BehaviorContext, VaultPrivateErrorServiceContract, StateInputType, VAULT_NOOP, DecisionOutcomeType, OperationType, InsightConfig, PipelineValue, StateEmitSnapshotShape, CellBuilderContract, VaultConfig, VaultRegistrationShape, BehaviorContract, FinalState, BehaviorClassContext } from '@sdux-vault/shared';
+import * as rxjs from 'rxjs';
+import { Subject } from 'rxjs';
+
+/**
+ * Core configuration contract for the pipeline orchestrator.
+ *
+ * This interface defines all inputs required to construct and
+ * execute the FeatureCell pipeline, including behaviors, callbacks,
+ * error handling services, and monitoring facilities.
+ *
+ * @typeParam T - The FeatureCell state value type.
+ */
+interface OrchestratorConfig<T> {
+    /**
+     * Tap callbacks invoked after state resolution.
+     */
+    afterTapCallbacks: TapCallback<T>[];
+    /**
+     * Tap callbacks invoked before state resolution.
+     */
+    beforeTapCallbacks: TapCallback<T>[];
+    /**
+     * Factories defining the behavior classes applied to the pipeline.
+     */
+    behaviors: BehaviorClassContract<T>[];
+    /**
+     * Optional set of behavior class factories applied when no explicit behaviors are provided.
+     */
+    defaultBehaviors?: BehaviorClassContract<T>[];
+    /**
+     * Behavior configuration values indexed by behavior config key.
+     */
+    behaviorConfigs: Map<string, unknown>;
+    /**
+     * The FeatureCell instance whose pipeline is being orchestrated.
+     */
+    cell: FeatureCellBaseShape<T>;
+    /**
+     * emitState callbacks invoked after state resolution.
+     */
+    emitStateCallbacks: CoreEmitStateCallback<T>[];
+    /**
+     * Error callbacks invoked before state resolution.
+     */
+    errorCallbacks: VaultErrorCallback<T>[];
+    /**
+     * Filter callbacks applied during the filter stage.
+     */
+    filterCallbacks: FilterFunction<T>[];
+    /**
+     * Initial state value that seeds the FeatureCell.
+     */
+    initialState: T | DeferredType<T>;
+    /**
+     * Reducer callbacks responsible for state transformation.
+     */
+    reducerCallbacks: ReducerFunction<T>[];
+    /**
+     * Interceptor behavior classes applied before pipeline execution.
+     */
+    interceptors: InterceptorBehaviorClassContract<T>[];
+    /**
+     * Operator behavior classes applied during pipeline execution.
+     */
+    operators: OperatorsBehaviorClassContract<T>[];
+}
+
+/**
+ * Configuration contract for the Conductor layer.
+ *
+ * This interface extends the base orchestrator configuration by
+ * declaring the controller classes that participate in pipeline
+ * decision-making for a FeatureCell.
+ *
+ * @typeParam T - The FeatureCell state value type.
+ */
+interface ConductorConfig<T> extends OrchestratorConfig<T> {
+    /**
+     * Factories defining the controller classes applied to the pipeline.
+     */
+    controllers: ControllerClassContract<T>[];
+}
+
+/**
+ * Defines the set of supported controller event type identifiers.
+ * This constant provides the canonical string values used to classify controller event outcomes.
+ */
+declare const ControllerEventTypes: {
+    /**
+     * Indicates that the controller requested an abort to terminate now.
+     */
+    readonly Abort: "abort";
+    /**
+     * Indicates that the controller execution resulted in a failure.
+     */
+    readonly Failure: "failure";
+    /**
+     * Indicates that the license controller approved the FeatureCell for operation.
+     */
+    readonly LicenseApproved: "licenseApproved";
+    /**
+     * Indicates that the license controller denied the FeatureCell for operation.
+     */
+    readonly LicenseDenied: "licenseDenied";
+    /**
+     * Indicates that the controller requested a revote.
+     */
+    readonly Revote: "revote";
+    /**
+     * Indicates that the controller execution completed successfully.
+     */
+    readonly Success: "success";
+};
+/**
+ * Represents the union of all valid controller event type values.
+ * This type constrains controller events to the supported identifiers defined by the event type registry.
+ *
+ * --RelatedStart--
+ * ControllerEventTypes
+ * --RelatedEnd--
+ */
+type ControllerEventType = (typeof ControllerEventTypes)[keyof typeof ControllerEventTypes];
+
+/**
+ * Describes the shape of an event emitted by a controller during execution.
+ * This interface defines the minimal contract required to identify the event type, associate it with a trace, and optionally carry error information.
+ *
+ * --RelatedStart--
+ * ControllerEventType
+ * --RelatedEnd--
+ */
+interface ControllerEventShape {
+    /**
+     * Identifies the type of controller event that occurred.
+     */
+    type: ControllerEventType;
+    /**
+     * Correlation identifier used to associate the event with a specific execution trace.
+     */
+    traceId: string;
+    /**
+     * Optional error value associated with the controller event.
+     */
+    error?: unknown;
+}
+
+/**
+ * Coordinates controller arbitration and lifecycle notifications.
+ *
+ * This class mediates between pipeline execution and registered controllers
+ * by delegating vote aggregation to the Arbitrator and emitting controller
+ * lifecycle events for monitoring and diagnostics.
+ */
+declare class DecisionEngine<T> {
+    #private;
+    private readonly controllers;
+    private readonly events$;
+    /**
+     * Creates a new decision engine instance.
+     *
+     * @param controllers - The controllers participating in pipeline decisions.
+     * @param events$ - Subject used to emit controller lifecycle events.
+     */
+    constructor(controllers: ControllerContract<T>[], events$: Subject<ControllerEventShape>);
+    /**
+     * Evaluates whether a pipeline execution attempt is permitted.
+     *
+     * @param ctx - The controller context for the current pipeline attempt.
+     * @returns An observable emitting the aggregated controller decision.
+     */
+    evaluateAttempt(ctx: ControllerContext<T>): rxjs.Observable<_sdux_vault_shared.ControllerDecisionShape>;
+    /**
+     * Notifies controllers that a pipeline execution completed successfully.
+     *
+     * @param ctx - The controller context associated with the successful run.
+     */
+    notifySuccess(ctx: ControllerContext<T>): void;
+    /**
+     * Notifies controllers that a pipeline execution failed.
+     *
+     * @param ctx - The controller context associated with the failure.
+     * @param error - The error that caused the pipeline to fail.
+     */
+    notifyFailure(ctx: ControllerContext<T>, error: VaultErrorShape | unknown): void;
+    /**
+     * Notifies controllers that a pipeline trace has finalized.
+     *
+     * @param ctx - The context associated with the finalized pipeline trace.
+     */
+    notifyFinalize(ctx: ControllerContext<T> | BehaviorContext<T>): void;
+}
+
+declare abstract class Orchestrator<T> {
+    #private;
+    protected cellKey: string;
+    protected decisionEngine: DecisionEngine<T>;
+    protected privateErrorService: VaultPrivateErrorServiceContract;
+    protected vaultMonitor: _sdux_vault_shared.VaultMonitorContract;
+    constructor(config: OrchestratorConfig<T>);
+    protected initializeOrchestrator(config: OrchestratorConfig<T>): void;
+    protected initializeFeatureCell(ctx: BehaviorContext<T>): Promise<void>;
+    protected destroyBehaviors(ctx: BehaviorContext<T>): void;
+    protected resetBehaviors(ctx: BehaviorContext<T>): void;
+    protected preparingIncoming(ctx: BehaviorContext<T>): StateInputType<T> | typeof VAULT_NOOP;
+    protected orchestrate(ctx: BehaviorContext<T>, options?: unknown): Promise<void>;
+    protected buildControllerCtx(ctx: BehaviorContext<T>): ControllerContext<T>;
+    protected normalizeIncoming<T>(incoming: StateInputType<T>): StateInputType<T>;
+    protected controllerOutcomeNotification(type: DecisionOutcomeType, ctx: BehaviorContext<T>): void;
+    protected prepIncomingForOrchestration(ctx: BehaviorContext<T>, incoming: StateInputType<T>, operation: OperationType): BehaviorContext<T>;
+}
+
+declare class Conductor<T> extends Orchestrator<T> {
+    #private;
+    constructor(config: ConductorConfig<T>);
+    initialize(ctx: BehaviorContext<T>): void;
+    conduct(ctx: BehaviorContext<T>, incoming: StateInputType<T>, operation: OperationType, options?: unknown): void;
+    /**
+     * Resets pipeline + controller state for this FeatureCell.
+     *
+     * FeatureCell should call this from its own reset() method.
+     */
+    reset(ctx: BehaviorContext<T>): void;
+    /**
+     * Destroys pipeline + controller state for this FeatureCell.
+     *
+     * FeatureCell should call this from its own destroy() method.
+     */
+    destroy(ctx: BehaviorContext<T>): void;
+}
+
+/**
+ * Declarative configuration for constructing a FeatureCell.
+ *
+ * This interface defines the minimum information required to
+ * identify, initialize, and optionally observe a FeatureCell
+ * instance within the Vault system.
+ *
+ * @typeParam T - The FeatureCell state value type.
+ */
+interface FeatureCellConfig<T> {
+    /**
+     * Unique identifier assigned to the FeatureCell instance.
+     */
+    key: string;
+    /**
+     * Initial state value that seeds the FeatureCell.
+     */
+    initialState: T;
+    /**
+     * Optional insight configuration used for enabling diagnostics
+     * or devtools-related observations.
+     */
+    insights?: InsightConfig;
+}
+
+/**
+ * Represents a reference view of Vault-managed state, including loading, value, and error signals.
+ */
+interface VaultStateRef<T> {
+    /**
+     * Indicates whether the state is currently loading.
+     */
+    isLoading: boolean;
+    /**
+     * Holds the current pipeline value for the state.
+     */
+    value: PipelineValue<T>;
+    /**
+     * Holds the current error state, if any.
+     */
+    error: VaultErrorShape | null;
+    /**
+     * Indicates whether a value is currently available.
+     */
+    hasValue: boolean;
+}
+
+/**
+ * Defines the public shape of a Feature Cell with an exposed resolved state reference.
+ * This interface extends the base Feature Cell contract by adding access to the reactive state produced by resolution.
+ *
+ * --RelatedStart--
+ * FeatureCellBaseShape
+ * VaultStateRef
+ * --RelatedEnd--
+ */
+interface FeatureCellShape<T> extends FeatureCellBaseShape<T> {
+    /**
+     * Reactive reference to the Feature Cell resolved state.
+     */
+    state: VaultStateRef<T>;
+}
+
+declare abstract class FeatureCellBuilder<T> {
+    #private;
+    protected readonly featureCellConfiguration: FeatureCellConfig<T>;
+    private readonly defaultBehaviors;
+    protected readonly behaviors: BehaviorClassContract<T>[];
+    protected readonly controllers: ControllerClassContract<T>[];
+    protected cell: FeatureCellBaseShape<T>;
+    protected readonly cellKey: string;
+    protected readonly ctx: BehaviorContext<T>;
+    protected readonly destroyed$: Subject<void>;
+    protected readonly reset$: Subject<void>;
+    protected readonly state$: Subject<StateEmitSnapshotShape<T>>;
+    constructor(featureCellConfiguration: FeatureCellConfig<T>, defaultBehaviors: BehaviorClassContract<T>[], behaviors: BehaviorClassContract<T>[], controllers: ControllerClassContract<T>[]);
+    protected reset(): void;
+    protected destroy(): void;
+    protected setup(): CellBuilderContract<T>;
+    protected mergeState(incoming: StateInputType<T>, options?: unknown): void;
+    protected replaceState(incoming: StateInputType<T>, options?: unknown): void;
+}
+
+declare class FeatureCellClass<T> extends FeatureCellBuilder<T> {
+    constructor(descriptor: FeatureCellConfig<T>, defaultBehaviors: BehaviorClassContract<T>[], behaviors: BehaviorClassContract<T>[], controllers: ControllerClassContract<T>[]);
+    build(): FeatureCellShape<T>;
+}
+
+interface RegisteredFeatureCellShape {
+    key: string;
+}
+
+declare function VaultCore(config?: VaultConfig): void;
+declare function registerFeatureCell(entry: RegisteredFeatureCellShape): void;
+declare function getLicensePayload(licenseId: string): unknown;
+declare function vaultAllSettled(): Promise<void>;
+declare function vaultSettled(key: string): Promise<void>;
+declare function registerVaultSettled(key: string, vaultSettled?: () => Promise<void>): void;
+/**
+ * Resets the global Vault configuration for isolated tests.
+ *
+ * This function should **never** be called in production builds.
+ */
+declare function resetVaultForTests(): void;
+declare function resetFeatureCellRegistry(): void;
+declare function getVaultRegistryForTests(): ReadonlyMap<string, VaultRegistrationShape> | undefined;
+
+/**
+ * Contract for behaviors that normalize raw errors into structured vault errors.
+ */
+interface CoreErrorBehaviorContract<T> extends BehaviorContract<T> {
+    /**
+     * Converts an unknown error value into a normalized vault error shape.
+     *
+     * @param error - The raw error value captured during execution.
+     * @param featureCellKey - The FeatureCell key where the error originated.
+     * @returns A normalized vault error representation.
+     */
+    handleError(error: unknown, featureCellKey: string): VaultErrorShape;
+}
+
+/**
+ * Contract for the core behavior responsible for committing pipeline state.
+ */
+interface CoreStateBehaviorContract<T> extends BehaviorContract<T> {
+    /**
+     * Finalizes an error state for the current pipeline execution.
+     *
+     * @param error - The error to commit or null to clear error state.
+     * @param ctx - The active behavior context.
+     */
+    finalizePipelineError(error: VaultErrorShape | null, ctx: BehaviorContext<T>): void;
+    /**
+     * Finalizes a resolved pipeline value.
+     *
+     * @param value - The computed pipeline result.
+     * @param ctx - The active behavior context.
+     */
+    finalizePipelineState(value: FinalState<T>, ctx: BehaviorContext<T>): void;
+    /**
+     * Finalizes a pipeline stop condition without applying state.
+     *
+     * @param ctx - The active behavior context.
+     */
+    finalizePipelineVaultStop(ctx: BehaviorContext<T>): void;
+    /**
+     * Prepares an incoming value for pipeline processing.
+     *
+     * @param ctx - The active behavior context.
+     * @returns The prepared input or a no-op sentinel.
+     */
+    preparePipelineIncoming(ctx: BehaviorContext<T>): StateInputType<T> | typeof VAULT_NOOP;
+    /**
+     * Finalizes a controller abort condition without applying state.
+     *
+     * @param ctx - The active behavior context.
+     */
+    finalizeControllerAbort(ctx: BehaviorContext<T>): void;
+    /**
+     * Finalizes a controller deny condition without applying state.
+     *
+     * @param ctx - The active behavior context.
+     */
+    finalizeControllerDeny(ctx: BehaviorContext<T>): void;
+}
+
+declare abstract class LicensingAbstract<T> {
+    #private;
+    static readonly needsLicense: boolean;
+    static readonly key: string;
+    constructor(ctx: BehaviorClassContext);
+    validateLicense(valid: boolean): void;
+}
+
+/**
+ * Defines the shape of a Feature Cell registration token.
+ * This type represents the minimal identifier required to reference a Feature Cell.
+ */
+type FeatureCellToken = {
+    /**
+     * Unique key associated with the Feature Cell.
+     */
+    key: string;
+};
+
+/**
+ * Creates a FeatureCell token for the specified key.
+ */
+declare function createFeatureCellToken(key: string): FeatureCellToken;
+/**
+ * Retrieves the FeatureCell token associated with a key.
+ */
+declare function getFeatureCellToken(key: string): FeatureCellToken;
+
+/**
+ * Determines whether a pipeline result is terminal.
+ *
+ * Terminal values indicate that the pipeline must halt without applying
+ * a new state snapshot. This includes both no-op and stop signals.
+ *
+ * @typeParam T - The FeatureCell state value type.
+ * @param current - The final pipeline result value.
+ * @returns `true` when the pipeline should not apply state.
+ */
+declare const isPipelineTerminal: <T>(current: FinalState<T>) => boolean;
+
+export { Conductor, FeatureCellClass, LicensingAbstract, VaultCore, createFeatureCellToken, getFeatureCellToken, getLicensePayload, getVaultRegistryForTests, isPipelineTerminal, registerFeatureCell, registerVaultSettled, resetFeatureCellRegistry, resetVaultForTests, vaultAllSettled, vaultSettled };
+export type { ConductorConfig, CoreErrorBehaviorContract, CoreStateBehaviorContract, FeatureCellConfig, FeatureCellShape, VaultStateRef };