@context-action/core

@context-action/core

Type-safe action pipeline management library for JavaScript/TypeScript applications.

Installation

npm install @context-action/core dotenv

Quick Start

1. Setup Environment Configuration

# Copy sample configuration
cp .env.sample .env

# Quick setup for maximum debugging detail
echo "NODE_ENV=development" >> .env
echo "CONTEXT_ACTION_TRACE=true" >> .env
echo "CONTEXT_ACTION_DEBUG=true" >> .env
echo "CONTEXT_ACTION_LOGGER_NAME=MyApp" >> .env

2. Basic Usage

// Load environment variables first
import 'dotenv/config';
import { ActionRegister } from '@context-action/core';

// Define your action types
interface MyActions {
  increment: void;
  setCount: number;
  updateUser: { id: string; name: string };
}

// Create action register
const actions = new ActionRegister<MyActions>();

// Register handlers
actions.register('increment', (_, controller) => {
  console.log('Increment called');
  // Handler automatically continues to next handler
});

actions.register('setCount', (count, controller) => {
  console.log(`Setting count to: ${count}`);
  // Handler automatically continues to next handler
});

// Dispatch actions
await actions.dispatch('increment');
await actions.dispatch('setCount', 42);

Environment Variables

Variable	Description	Default	Max Detail
CONTEXT_ACTION_TRACE	Enable detailed trace logging	false	true
CONTEXT_ACTION_DEBUG	Enable debug mode	false	true
CONTEXT_ACTION_LOG_LEVEL	Set specific log level (TRACE, DEBUG, INFO, WARN, ERROR, NONE)	ERROR	TRACE
CONTEXT_ACTION_LOGGER_NAME	Custom logger name	ActionRegister	YourAppName
NODE_ENV	Auto-configure logging (development = DEBUG, production = ERROR)	-	development

💡 Tip: For maximum debugging detail, set all variables in the "Max Detail" column.

Features

• Type-safe actions - Full TypeScript support with compile-time checking
• Priority-based execution - Control handler execution order
• Pipeline control - Abort, modify payloads, conditional execution
• Event system - Listen to action lifecycle events
• Comprehensive logging - Detailed trace logging for debugging
• Environment-based configuration - Easy .env setup

Advanced Usage

Handler Configuration

actions.register('myAction', handler, {
  priority: 10,        // Higher priority executes first
  blocking: true,      // Wait for async handlers
  once: true,         // Remove after first execution
  condition: () => shouldRun, // Conditional execution
  id: 'my-handler'    // Custom handler ID
});

Pipeline Control

actions.register('validate', (data, controller) => {
  if (!data.isValid) {
    controller.abort('Validation failed');
    return;
  }
  
  // Modify data for next handlers
  controller.modifyPayload(data => ({ ...data, validated: true }));
  // Handler automatically continues to next handler
});

Event Listeners

actions.on('action:start', ({ action, payload }) => {
  console.log(`Starting ${action}`, payload);
});

actions.on('action:complete', ({ action, metrics }) => {
  console.log(`Completed ${action} in ${metrics.executionTime}ms`);
});

Debugging

Maximum Detail Logging

For the most comprehensive debugging experience, use this .env configuration:

# .env - Maximum detail logging configuration
NODE_ENV=development
CONTEXT_ACTION_TRACE=true
CONTEXT_ACTION_DEBUG=true
CONTEXT_ACTION_LOGGER_NAME=DetailedApp

# This configuration will show:
# - Every function call and return
# - Handler registration and execution details
# - Pipeline flow and state changes
# - Payload modifications and conditions
# - Performance metrics and timing
# - Error details and stack traces

Common Debug Configurations

# Development - Balanced detail
NODE_ENV=development
CONTEXT_ACTION_DEBUG=true
CONTEXT_ACTION_LOGGER_NAME=DevApp

# Production Debug - Errors only with context
NODE_ENV=production
CONTEXT_ACTION_LOG_LEVEL=ERROR
CONTEXT_ACTION_DEBUG=true
CONTEXT_ACTION_LOGGER_NAME=ProdApp

# Issue Investigation - Specific level
CONTEXT_ACTION_LOG_LEVEL=DEBUG
CONTEXT_ACTION_DEBUG=true
CONTEXT_ACTION_LOGGER_NAME=InvestigationSession

Test Your Configuration

After setting up your .env file, test that maximum detail logging is working:

# Create a quick test file
echo "import 'dotenv/config';
import { ActionRegister } from '@context-action/core';

const actions = new ActionRegister();
actions.register('test', (payload, controller) => {
  console.log('Handler executed:', payload);
  // Handler automatically continues to next handler
});
await actions.dispatch('test', { message: 'Hello!' });" > test-logging.js

# Run the test
node test-logging.js

You should see detailed TRACE and DEBUG output if configured correctly.

Troubleshooting

Not seeing trace output?

• Check dependencies: Make sure dotenv is installed

  npm install dotenv
  # or
  pnpm install dotenv
  

• Verify .env file: Confirm your .env file exists and has the correct settings

  cat .env
  # Should show: CONTEXT_ACTION_TRACE=true
  

• Check import order: dotenv/config must be imported first

  import 'dotenv/config'; // MUST be first
  import { ActionRegister } from '@context-action/core';
  

• Rebuild if needed: After installing dotenv, rebuild the project if using a bundler

For detailed debugging information, see TRACE_LOGGING.md.

API Reference

ActionRegister

Main class for managing action pipelines.

• register<K>(action, handler, config?) - Register action handler
• dispatch<K>(action, payload?) - Dispatch action through pipeline
• getHandlerCount(action) - Get number of handlers for action
• hasHandlers(action) - Check if action has handlers
• clearAction(action) - Remove all handlers for action
• clearAll() - Remove all handlers
• on(event, handler) - Add event listener

Configuration Options

interface ActionRegisterConfig {
  logger?: Logger;           // Custom logger implementation
  logLevel?: LogLevel;       // Log filtering level
  name?: string;            // Logger name
  debug?: boolean;          // Enable debug mode
}

TypeScript Support

Full TypeScript support with compile-time type checking:

interface AppActions {
  // Action without payload
  reset: void;
  
  // Action with payload
  setUser: { id: string; name: string };
  
  // Action with optional payload
  navigate: string | undefined;
}

const actions = new ActionRegister<AppActions>();

// ✅ Type-safe dispatch
await actions.dispatch('reset');
await actions.dispatch('setUser', { id: '1', name: 'John' });

// ❌ TypeScript error - missing payload
await actions.dispatch('setUser');

// ❌ TypeScript error - wrong payload type
await actions.dispatch('setUser', 'invalid');

License

Apache-2.0

Contributing

See the main repository for contribution guidelines.