@almadar/runtime 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,291 @@
+import { B as BindingContext, T as TraitState, a as TraitDefinition, b as TransitionResult, E as EffectHandlers, c as EffectContext } from './types-JFCKD0FU.js';
+export { d as Effect, e as EventListener, I as IEventBus, R as RuntimeEvent, U as Unsubscribe } from './types-JFCKD0FU.js';
+export { E as EntitySharingMap, a as EventBus, b as EventNamespaceMap, O as OrbitalEventRequest, c as OrbitalEventResponse, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, e as PreprocessOptions, f as PreprocessResult, g as PreprocessedSchema, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, j as getIsolatedCollectionName, k as getNamespacedEvent, l as isNamespacedEvent, p as parseNamespacedEvent, m as preprocessSchema } from './OrbitalServerRuntime-COj7K1yM.js';
+import { EvaluationContext } from '@almadar/evaluator';
+export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
+export { ServerBridgeConfig, ServerBridgeState } from './ServerBridge.js';
+import 'express';
+import '@almadar/core';
+
+/**
+ * BindingResolver - Platform-Agnostic Binding Resolution
+ *
+ * Resolves binding references like @entity.field, @payload.value, @state
+ * in props and values. Works on both client and server.
+ *
+ * Uses the shared S-expression evaluator for actual resolution.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Interpolate binding references in props.
+ *
+ * @param props - Props object with potential binding references
+ * @param ctx - Evaluation context with bindings
+ * @returns New props object with resolved values
+ *
+ * @example
+ * ```ts
+ * const ctx = createContextFromBindings({ name: 'Project Alpha', count: 42 });
+ * const props = {
+ *   title: '@entity.name',
+ *   total: ['+', '@entity.count', 10],
+ * };
+ * const result = interpolateProps(props, ctx);
+ * // { title: 'Project Alpha', total: 52 }
+ * ```
+ */
+declare function interpolateProps(props: Record<string, unknown>, ctx: EvaluationContext): Record<string, unknown>;
+/**
+ * Interpolate a single value.
+ */
+declare function interpolateValue(value: unknown, ctx: EvaluationContext): unknown;
+/**
+ * Check if a value contains any binding references.
+ */
+declare function containsBindings(value: unknown): boolean;
+/**
+ * Extract all binding references from a value.
+ */
+declare function extractBindings(value: unknown): string[];
+/**
+ * Create an EvaluationContext from a BindingContext.
+ */
+declare function createContextFromBindings(bindings: BindingContext): EvaluationContext;
+
+/**
+ * StateMachineCore - Platform-Agnostic State Machine Logic
+ *
+ * Pure TypeScript implementation of trait state machine execution.
+ * Extracts the core logic from useTraitStateMachine for use on
+ * both client and server.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Find the initial state for a trait definition.
+ */
+declare function findInitialState(trait: TraitDefinition): string;
+/**
+ * Create initial trait state for a trait definition.
+ */
+declare function createInitialTraitState(trait: TraitDefinition): TraitState;
+/**
+ * Find a matching transition from the current state for the given event.
+ */
+declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string): TraitDefinition['transitions'][0] | undefined;
+/**
+ * Normalize event key - strip UI: prefix if present.
+ */
+declare function normalizeEventKey(eventKey: string): string;
+/**
+ * Options for processing an event through the state machine.
+ */
+interface ProcessEventOptions {
+    /** Current trait state */
+    traitState: TraitState;
+    /** Trait definition */
+    trait: TraitDefinition;
+    /** Event key to process */
+    eventKey: string;
+    /** Event payload */
+    payload?: Record<string, unknown>;
+    /** Entity data for binding resolution */
+    entityData?: Record<string, unknown>;
+}
+/**
+ * Process an event through a trait's state machine.
+ *
+ * This is a pure function that:
+ * 1. Finds matching transitions
+ * 2. Evaluates guards
+ * 3. Returns the transition result (but does not execute effects)
+ *
+ * @returns TransitionResult with effects to execute
+ *
+ * @example
+ * ```ts
+ * const result = processEvent({
+ *   traitState: { traitName: 'Cart', currentState: 'empty', ... },
+ *   trait: cartTraitDefinition,
+ *   eventKey: 'ADD_ITEM',
+ *   payload: { productId: '123' },
+ * });
+ *
+ * if (result.executed) {
+ *   // Execute effects
+ *   for (const effect of result.effects) {
+ *     effectExecutor.execute(effect);
+ *   }
+ *   // Update state
+ *   traitState.currentState = result.newState;
+ * }
+ * ```
+ */
+declare function processEvent(options: ProcessEventOptions): TransitionResult;
+/**
+ * Stateful manager for multiple trait state machines.
+ *
+ * Platform-agnostic - can be used directly on server or wrapped
+ * in a React hook on client.
+ *
+ * @example
+ * ```ts
+ * const manager = new StateMachineManager([cartTrait, userTrait]);
+ *
+ * // Process event
+ * const results = manager.sendEvent('ADD_ITEM', { productId: '123' });
+ *
+ * // Get current states
+ * const cartState = manager.getState('Cart');
+ * ```
+ */
+declare class StateMachineManager {
+    private traits;
+    private states;
+    constructor(traits?: TraitDefinition[]);
+    /**
+     * Add a trait to the manager.
+     */
+    addTrait(trait: TraitDefinition): void;
+    /**
+     * Remove a trait from the manager.
+     */
+    removeTrait(traitName: string): void;
+    /**
+     * Get current state for a trait.
+     */
+    getState(traitName: string): TraitState | undefined;
+    /**
+     * Get all current states.
+     */
+    getAllStates(): Map<string, TraitState>;
+    /**
+     * Check if a trait can handle an event from its current state.
+     */
+    canHandleEvent(traitName: string, eventKey: string): boolean;
+    /**
+     * Send an event to all traits.
+     *
+     * @returns Array of transition results (one per trait that had a matching transition)
+     */
+    sendEvent(eventKey: string, payload?: Record<string, unknown>, entityData?: Record<string, unknown>): Array<{
+        traitName: string;
+        result: TransitionResult;
+    }>;
+    /**
+     * Reset a trait to its initial state.
+     */
+    resetTrait(traitName: string): void;
+    /**
+     * Reset all traits to initial states.
+     */
+    resetAll(): void;
+}
+
+/**
+ * EffectExecutor - Platform-Agnostic Effect Dispatch
+ *
+ * Routes S-expression effects to appropriate handlers.
+ * Platform-specific adapters provide handler implementations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Full executor options with handlers and context.
+ */
+interface EffectExecutorOptions {
+    /** Effect handlers (platform-specific) */
+    handlers: EffectHandlers;
+    /** Binding context for resolving @entity.field references */
+    bindings: BindingContext;
+    /** Effect execution context (trait name, state, etc.) */
+    context: EffectContext;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * EffectExecutor - Routes effects to handlers.
+ *
+ * @example
+ * ```ts
+ * const executor = new EffectExecutor({
+ *   handlers: {
+ *     emit: (event, payload) => eventBus.emit(event, payload),
+ *     persist: async (action, entity, data) => { ... },
+ *     set: (id, field, value) => { ... },
+ *     callService: async (service, action, params) => { ... },
+ *   },
+ *   bindings: { entity: { name: 'Product' }, payload: { id: '123' } },
+ *   context: { traitName: 'Cart', state: 'active', transition: 'idle->active' },
+ * });
+ *
+ * // Execute a single effect
+ * executor.execute(['emit', 'ITEM_ADDED', { count: 1 }]);
+ *
+ * // Execute multiple effects
+ * executor.executeAll([
+ *   ['set', 'item', 'quantity', 5],
+ *   ['emit', 'QUANTITY_UPDATED'],
+ * ]);
+ * ```
+ */
+declare class EffectExecutor {
+    private handlers;
+    private bindings;
+    private context;
+    private debug;
+    constructor(options: EffectExecutorOptions);
+    /**
+     * Execute a single effect.
+     */
+    execute(effect: unknown): Promise<void>;
+    /**
+     * Execute multiple effects in sequence.
+     */
+    executeAll(effects: unknown[]): Promise<void>;
+    /**
+     * Execute multiple effects in parallel.
+     */
+    executeParallel(effects: unknown[]): Promise<void>;
+    private dispatch;
+    private logUnsupported;
+}
+/**
+ * Create a minimal EffectExecutor for testing or simple scenarios.
+ */
+declare function createTestExecutor(overrides?: Partial<EffectHandlers>): EffectExecutor;
+
+/**
+ * MockPersistenceAdapter - In-memory data store with faker-based mock generation
+ *
+ * Provides a stateful mock data layer that implements PersistenceAdapter.
+ * Uses @faker-js/faker for realistic data generation based on field types.
+ *
+ * @packageDocumentation
+ */
+
+interface EntityField {
+    name: string;
+    type: string;
+    required?: boolean;
+    values?: string[];
+    default?: unknown;
+}
+interface EntitySchema {
+    name: string;
+    fields: EntityField[];
+}
+interface MockPersistenceConfig {
+    /** Seed for deterministic generation */
+    seed?: number;
+    /** Default number of records to generate per entity */
+    defaultSeedCount?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+export { BindingContext, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, type EntityField, type EntitySchema, type MockPersistenceConfig, type ProcessEventOptions, StateMachineManager, TraitDefinition, TraitState, TransitionResult, containsBindings, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, interpolateProps, interpolateValue, normalizeEventKey, processEvent };