owservable

@owservable/actions

A TypeScript library implementing the Action Pattern for creating reusable, executable units of work that can be run as commands, cronjobs, watchers, workers, or controllers.

🚀 Features

Action Pattern Implementation: Structured approach to organizing business logic
Multiple Execution Contexts: Run actions as commands, cronjobs, watchers, workers, or controllers
Commander.js Integration: Built-in CLI command support with option parsing
TypeScript Support: Full type safety with comprehensive interfaces
Flexible Architecture: Abstract base class with specialized interfaces

📦 Installation

npm install @owservable/actions

yarn add @owservable/actions

pnpm add @owservable/actions

🔧 Usage

Basic Action Implementation

import { Action, ActionInterface } from '@owservable/actions';

class MyAction extends Action implements ActionInterface {
  protected _description = 'My custom action';

  async handle(...args: any[]): Promise<any> {
    // Your business logic here
    console.log('Action executed with args:', args);
    return { success: true };
  }

  description(): string {
    return this._description;
  }
}

Command Line Action

import { Action, ActionAsCommandInterface } from '@owservable/actions';

class MyCommandAction extends Action implements ActionAsCommandInterface {
  protected _signature = 'my-command {--option=default}';
  protected _description = 'My command action';

  async handle(...args: any[]): Promise<any> {
    // Your business logic here
    return { success: true };
  }

  async asCommand(options: any): Promise<void> {
    console.log('Command executed with options:', options);
    await this.handle(options);
  }

  signature(): string {
    return this._signature;
  }

  description(): string {
    return this._description;
  }
}

Running Actions as Commands

import { runActionAsCommand } from '@owservable/actions';

const action = new MyCommandAction();
await runActionAsCommand(action);

Cronjob Action

import { Action, ActionAsCronjobInterface } from '@owservable/actions';

class MyCronjobAction extends Action implements ActionAsCronjobInterface {
  protected _schedule = '0 0 * * *'; // Daily at midnight
  protected _description = 'Daily cleanup job';

  async handle(...args: any[]): Promise<any> {
    // Your cronjob logic here
    return { success: true };
  }

  async asCronjob(): Promise<void> {
    console.log('Cronjob executed');
    await this.handle();
  }

  schedule(): string {
    return this._schedule;
  }

  description(): string {
    return this._description;
  }
}

Watcher Action

import { Action, ActionAsWatcherInterface } from '@owservable/actions';

class MyWatcherAction extends Action implements ActionAsWatcherInterface {
  protected _description = 'File watcher action';

  async handle(...args: any[]): Promise<any> {
    // Your watcher logic here
    return { success: true };
  }

  async asWatcher(): Promise<void> {
    console.log('Watcher executed');
    await this.handle();
  }

  description(): string {
    return this._description;
  }
}

📚 API Documentation

Base Classes

`Action`

Abstract base class providing common functionality for all actions.

Properties:

_signature: Command signature for CLI actions
_description: Human-readable description
_schedule: Cron schedule for cronjob actions

Methods:

signature(): Returns the command signature
description(): Returns the action description
schedule(): Returns the cron schedule

Interfaces

`ActionInterface`

Base interface that all actions must implement.

Methods:

description(): string - Returns action description
handle(...args: any[]): Promise<any> - Main action logic