TypeScript Types

ScriptIt is built with TypeScript and provides comprehensive type definitions for all its APIs. This page documents all the types, interfaces, and type utilities available when using ScriptIt in TypeScript projects.

Core Types

`createScriptRunner`

The main function for creating script runner instances.

typescript

function createScriptRunner(
  options?: CreateScriptRunnerOptions
): Promise<ScriptRunnerInstance>

Configuration Types

`CreateScriptRunnerOptions`

Configuration options for creating a script runner instance.

typescript

interface CreateScriptRunnerOptions 
  extends Partial<Omit<RunnerConfig, "loadedConfigPath">> {
  
  // Configuration file
  configFile?: string;
  
  // Environment configuration
  initialEnv?: Record<string, string | undefined>;
  
  // Working directory
  workingDirectory?: string;
  
  // Console interception configuration
  consoleInterception?: {
    enabled?: boolean;
    includeLevel?: boolean;
    preserveOriginal?: boolean;
    useColors?: boolean;
  };
}

Properties:

Property	Type	Description
`configFile`	`string`	Path to configuration file
`initialEnv`	`Record<string, string \| undefined>`	Initial environment variables
`workingDirectory`	`string`	Working directory for script execution
`consoleInterception`	`ConsoleInterceptionOptions`	Console interception settings
`scriptsDir`	`string`	Directory containing scripts (inherited)
`tmpDir`	`string`	Temporary files directory (inherited)
`envFiles`	`string[]`	Environment files to load (inherited)
`defaultParams`	`Record<string, unknown>`	Default parameters (inherited)
`excludePatterns`	`string[]`	Glob patterns to exclude (inherited)

`RunnerConfig`

Base configuration interface for the script runner.

typescript

interface RunnerConfig {
  scriptsDir: string;
  tmpDir: string;
  envFiles: string[];
  defaultParams?: Record<string, unknown>;
  loadedConfigPath?: string;
  excludePatterns?: string[];
}

`EffectiveConfig`

Resolved configuration after loading and merging all sources.

typescript

interface EffectiveConfig extends RunnerConfig {
  loadedConfigPath: string | null;
  // All properties are resolved and non-optional where applicable
}

Script Runner Instance Types

`ScriptRunnerInstance`

The main interface for script runner instances returned by createScriptRunner().

typescript

interface ScriptRunnerInstance {
  // Properties
  config: EffectiveConfig;
  environment: Record<string, string | undefined>;
  
  // Methods
  executeScript: (
    scriptPath: string,
    executionParams?: ExecutionParams,
    customLogger?: LoggerFunction
  ) => Promise<ScriptExecutionResult>;
  
  listScripts: () => Promise<string[]>;
  runTUI: () => Promise<void>;
  
  // Event methods
  on: <K extends keyof ScriptEventHandler>(
    eventName: K,
    listener: ScriptEventHandler[K]
  ) => ScriptRunnerInstance;
  
  off: <K extends keyof ScriptEventHandler>(
    eventName: K,
    listener: ScriptEventHandler[K]
  ) => ScriptRunnerInstance;
  
  emit: <K extends keyof ScriptEventHandler>(
    eventName: K,
    ...args: Parameters<ScriptEventHandler[K]>
  ) => boolean;
}

`ExecutionParams`

Parameters for script execution.

typescript

interface ExecutionParams {
  params?: Record<string, unknown>;
  env?: Record<string, string>;
  contextOverrides?: Record<string, unknown>;
}

Properties:

Property	Type	Description
`params`	`Record<string, unknown>`	Parameters passed to the script
`env`	`Record<string, string>`	Environment variable overrides
`contextOverrides`	`Record<string, unknown>`	Context property overrides

`ScriptExecutionResult`

Result returned from script execution.

typescript

interface ScriptExecutionResult {
  [key: string]: unknown;
}

Scripts can return any data structure, which will be preserved in the result.

`LoggerFunction`

Type for custom logging functions.

typescript

type LoggerFunction = (message: string) => void;

Script Types

`ScriptModule`

Interface that scripts must implement.

typescript

interface ScriptModule {
  // Lifecycle methods
  tearUp?: (context: ScriptContext) => Promise<unknown> | unknown;
  execute?: (
    context: ScriptContext,
    tearUpResult?: unknown
  ) => Promise<unknown> | unknown;
  tearDown?: (
    context: ScriptContext,
    executeResult?: unknown,
    tearUpResult?: unknown
  ) => Promise<void> | void;
  
  // Alternative entry point
  default?: (
    context: ScriptContext,
    tearUpResult?: unknown
  ) => Promise<unknown> | unknown;
  
  // Metadata
  description?: string;
}

Methods:

Method	Type	Description
`tearUp`	`(context: ScriptContext) => Promise<unknown> \| unknown`	Setup phase (optional)
`execute`	`(context: ScriptContext, tearUpResult?: unknown) => Promise<unknown> \| unknown`	Main execution (optional if default exists)
`tearDown`	`(context: ScriptContext, executeResult?: unknown, tearUpResult?: unknown) => Promise<void> \| void`	Cleanup phase (optional)
`default`	`(context: ScriptContext, tearUpResult?: unknown) => Promise<unknown> \| unknown`	Alternative entry point (optional)

Properties:

Property	Type	Description
`description`	`string`	Script description for UI display

`ScriptContext`

Context object passed to scripts during execution.

typescript

interface ScriptContext {
  // Environment and configuration
  env: Record<string, string | undefined>;
  tmpDir: string;
  configPath?: string;
  
  // Logging and parameters
  log: LoggerFunction;
  params: Record<string, unknown>;
  
  // Enhanced console (when console interception is enabled)
  console?: ColoredConsole;
  
  // Additional context properties from defaultParams and contextOverrides
  [key: string]: unknown;
}

Properties:

Property	Type	Description
`env`	`Record<string, string \| undefined>`	Environment variables
`tmpDir`	`string`	Temporary directory path
`configPath`	`string`	Path to loaded configuration file
`log`	`LoggerFunction`	Logging function
`params`	`Record<string, unknown>`	Script parameters
`console`	`ColoredConsole`	Enhanced console with colors (optional)

`ColoredConsole`

Enhanced console interface with colored output methods.

typescript

interface ColoredConsole {
  log: (...args: any[]) => void;      // White output
  error: (...args: any[]) => void;    // Red output
  warn: (...args: any[]) => void;     // Yellow output
  info: (...args: any[]) => void;     // Blue output
  debug: (...args: any[]) => void;    // Gray output
}

Event System Types

`ScriptEventHandler`

Type definitions for all available events.

typescript

type ScriptEventHandler = {
  'script:beforeExecute': (
    scriptPath: string, 
    params: Record<string, unknown>
  ) => void;
  
  'script:afterExecute': (
    scriptPath: string, 
    result: ScriptExecutionResult
  ) => void;
  
  'script:error': (
    scriptPath: string, 
    error: unknown
  ) => void;
  
  'script:log': (
    scriptPath: string, 
    message: string
  ) => void;
  
  'tui:beforeStart': () => void;
  'tui:afterEnd': () => void;
};

Events:

Event	Parameters	Description
`script:beforeExecute`	`scriptPath: string, params: Record<string, unknown>`	Fired before script execution
`script:afterExecute`	`scriptPath: string, result: ScriptExecutionResult`	Fired after successful execution
`script:error`	`scriptPath: string, error: unknown`	Fired when script execution fails
`script:log`	`scriptPath: string, message: string`	Fired when script logs a message
`tui:beforeStart`	None	Fired before TUI starts
`tui:afterEnd`	None	Fired after TUI ends

Console Interception Types

`ConsoleInterceptionOptions`

Configuration for console interception.

typescript

interface ConsoleInterceptionOptions {
  enabled?: boolean;
  includeLevel?: boolean;
  preserveOriginal?: boolean;
  useColors?: boolean;
}

Properties:

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Enable console interception
`includeLevel`	`boolean`	`false`	Include log level in output
`preserveOriginal`	`boolean`	`false`	Preserve original console methods
`useColors`	`boolean`	`true`	Enable colored output

`ScriptExecutorOptions`

Options for script executor configuration.

typescript

interface ScriptExecutorOptions {
  consoleInterception?: {
    enabled: boolean;
    logFunction?: LoggerFunction;
    includeLevel?: boolean;
    preserveOriginal?: boolean;
    useColors?: boolean;
  };
}

Utility Types

`EventEmitterMethods`

Type for event emitter methods on the script runner instance.

typescript

type EventEmitterMethods<T> = {
  on: <K extends keyof T>(
    eventName: K,
    listener: T[K]
  ) => ScriptRunnerInstance;
  
  off: <K extends keyof T>(
    eventName: K,
    listener: T[K]
  ) => ScriptRunnerInstance;
  
  emit: <K extends keyof T>(
    eventName: K,
    ...args: Parameters<T[K]>
  ) => boolean;
};

`PartialConfig`

Utility type for partial configuration objects.

typescript

type PartialConfig<T> = {
  [P in keyof T]?: T[P];
};

Type Guards

`isScriptModule`

Type guard to check if an object implements the ScriptModule interface.

typescript

function isScriptModule(obj: any): obj is ScriptModule {
  return obj && 
    (typeof obj.execute === 'function' || typeof obj.default === 'function');
}

`hasExecuteFunction`

Type guard to check if a script module has an execute function.

typescript

function hasExecuteFunction(module: ScriptModule): module is ScriptModule & {
  execute: NonNullable<ScriptModule['execute']>;
} {
  return typeof module.execute === 'function';
}

`hasDefaultFunction`

Type guard to check if a script module has a default function.

typescript

function hasDefaultFunction(module: ScriptModule): module is ScriptModule & {
  default: NonNullable<ScriptModule['default']>;
} {
  return typeof module.default === 'function';
}

Usage Examples

Basic TypeScript Usage

typescript

import { 
  createScriptRunner, 
  type CreateScriptRunnerOptions,
  type ScriptExecutionResult,
  type ScriptEventHandler
} from '@glyphtek/scriptit';

const options: CreateScriptRunnerOptions = {
  scriptsDir: './scripts',
  tmpDir: './tmp',
  consoleInterception: {
    enabled: true,
    useColors: true
  }
};

const runner = await createScriptRunner(options);
const result: ScriptExecutionResult = await runner.executeScript('script.js');

Typed Script Results

typescript

import { createScriptRunner, type ScriptExecutionResult } from '@glyphtek/scriptit';

// Define expected result structure
interface ProcessingResult {
  success: boolean;
  processedFiles: number;
  errors: string[];
  duration: number;
}

async function runProcessingScript(): Promise<ProcessingResult> {
  const runner = await createScriptRunner({
    scriptsDir: './scripts',
    tmpDir: './tmp'
  });

  const result: ScriptExecutionResult = await runner.executeScript('process-data.ts');
  
  // Type assertion with validation
  if (typeof result === 'object' && result !== null) {
    return result as ProcessingResult;
  }
  
  throw new Error('Invalid script result structure');
}

Event Handler Typing

typescript

import { createScriptRunner, type ScriptEventHandler } from '@glyphtek/scriptit';

const runner = await createScriptRunner({
  scriptsDir: './scripts',
  tmpDir: './tmp'
});

// Type-safe event handlers
const beforeExecuteHandler: ScriptEventHandler['script:beforeExecute'] = 
  (scriptPath, params) => {
    console.log(`Starting: ${scriptPath}`, params);
  };

const afterExecuteHandler: ScriptEventHandler['script:afterExecute'] = 
  (scriptPath, result) => {
    console.log(`Completed: ${scriptPath}`, result);
  };

runner.on('script:beforeExecute', beforeExecuteHandler);
runner.on('script:afterExecute', afterExecuteHandler);

Custom Script Context

typescript

import { type ScriptContext } from '@glyphtek/scriptit';

// Extend context with custom properties
interface CustomScriptContext extends ScriptContext {
  database: DatabaseConnection;
  cache: CacheService;
  metrics: MetricsCollector;
}

// Script with typed context
export async function execute(context: CustomScriptContext) {
  const console = context.console || global.console;
  
  // Access typed custom properties
  const users = await context.database.getUsers();
  const cachedData = await context.cache.get('user-data');
  
  context.metrics.increment('script.execution');
  
  console.log(`Processed ${users.length} users`);
  
  return {
    success: true,
    userCount: users.length,
    cacheHit: !!cachedData
  };
}

Generic Script Execution

typescript

import { createScriptRunner, type ScriptExecutionResult } from '@glyphtek/scriptit';

// Generic function for typed script execution
async function executeTypedScript<T = ScriptExecutionResult>(
  scriptPath: string,
  params?: Record<string, unknown>
): Promise<T> {
  const runner = await createScriptRunner({
    scriptsDir: './scripts',
    tmpDir: './tmp'
  });

  const result = await runner.executeScript(scriptPath, { params });
  return result as T;
}

// Usage with specific types
interface DeployResult {
  deployed: boolean;
  version: string;
  artifacts: string[];
}

const deployResult = await executeTypedScript<DeployResult>('deploy.ts', {
  environment: 'production',
  version: '1.2.0'
});

console.log(`Deployed version ${deployResult.version}`);
console.log(`Artifacts: ${deployResult.artifacts.join(', ')}`);

Configuration with Type Safety

typescript

import { 
  createScriptRunner, 
  type CreateScriptRunnerOptions,
  type RunnerConfig 
} from '@glyphtek/scriptit';

// Type-safe configuration builder
class ScriptRunnerConfigBuilder {
  private config: Partial<CreateScriptRunnerOptions> = {};

  scriptsDirectory(dir: string): this {
    this.config.scriptsDir = dir;
    return this;
  }

  temporaryDirectory(dir: string): this {
    this.config.tmpDir = dir;
    return this;
  }

  environmentFiles(...files: string[]): this {
    this.config.envFiles = files;
    return this;
  }

  excludePatterns(...patterns: string[]): this {
    this.config.excludePatterns = patterns;
    return this;
  }

  enableConsoleColors(enabled: boolean = true): this {
    this.config.consoleInterception = {
      ...this.config.consoleInterception,
      enabled,
      useColors: enabled
    };
    return this;
  }

  build(): CreateScriptRunnerOptions {
    return { ...this.config };
  }
}

// Usage
const config = new ScriptRunnerConfigBuilder()
  .scriptsDirectory('./src/scripts')
  .temporaryDirectory('./temp')
  .environmentFiles('.env', '.env.local')
  .excludePatterns('*.test.ts', '_*')
  .enableConsoleColors(true)
  .build();

const runner = await createScriptRunner(config);

Type Declarations

If you're using ScriptIt in a TypeScript project, the types are automatically included. For JavaScript projects with TypeScript checking, you can reference the types:

typescript

// types.d.ts
/// <reference types="@glyphtek/scriptit" />

declare module '@glyphtek/scriptit' {
  // Additional type augmentations if needed
}

Advanced Type Patterns

Script Factory Pattern

typescript

import { type ScriptContext, type ScriptModule } from '@glyphtek/scriptit';

// Factory for creating typed scripts
function createScript<TParams = Record<string, unknown>, TResult = unknown>(
  implementation: (context: ScriptContext, params: TParams) => Promise<TResult> | TResult
): ScriptModule {
  return {
    async execute(context: ScriptContext): Promise<TResult> {
      const params = context.params as TParams;
      return await implementation(context, params);
    }
  };
}

// Usage
interface ProcessParams {
  inputFile: string;
  outputDir: string;
  format: 'json' | 'csv';
}

interface ProcessResult {
  success: boolean;
  outputFiles: string[];
  recordCount: number;
}

export default createScript<ProcessParams, ProcessResult>(
  async (context, params) => {
    const console = context.console || global.console;
    
    console.log(`Processing ${params.inputFile}`);
    console.log(`Output format: ${params.format}`);
    
    // Implementation...
    
    return {
      success: true,
      outputFiles: [`${params.outputDir}/output.${params.format}`],
      recordCount: 100
    };
  }
);

Event-Driven Architecture

typescript

import { 
  createScriptRunner, 
  type ScriptEventHandler,
  type ScriptExecutionResult 
} from '@glyphtek/scriptit';

// Typed event bus
class ScriptEventBus {
  private handlers: Partial<ScriptEventHandler> = {};

  on<K extends keyof ScriptEventHandler>(
    event: K,
    handler: ScriptEventHandler[K]
  ): void {
    this.handlers[event] = handler;
  }

  setupRunner(runner: any): void {
    Object.entries(this.handlers).forEach(([event, handler]) => {
      if (handler) {
        runner.on(event as keyof ScriptEventHandler, handler);
      }
    });
  }
}

// Usage
const eventBus = new ScriptEventBus();

eventBus.on('script:beforeExecute', (scriptPath, params) => {
  console.log(`🚀 Starting ${scriptPath}`);
});

eventBus.on('script:afterExecute', (scriptPath, result) => {
  console.log(`✅ Completed ${scriptPath}`);
});

const runner = await createScriptRunner({
  scriptsDir: './scripts',
  tmpDir: './tmp'
});

eventBus.setupRunner(runner);

Library API - Main API documentation
Event System - Event system details
CLI Commands - CLI type equivalents
Examples - TypeScript usage examples

TypeScript Types ​

Core Types ​

createScriptRunner ​

Configuration Types ​

CreateScriptRunnerOptions ​

RunnerConfig ​

EffectiveConfig ​

Script Runner Instance Types ​

ScriptRunnerInstance ​

ExecutionParams ​

ScriptExecutionResult ​

LoggerFunction ​

Script Types ​

ScriptModule ​

ScriptContext ​

ColoredConsole ​

Event System Types ​

ScriptEventHandler ​

Console Interception Types ​

ConsoleInterceptionOptions ​

ScriptExecutorOptions ​

Utility Types ​

EventEmitterMethods ​

PartialConfig ​

Type Guards ​

isScriptModule ​

hasExecuteFunction ​

hasDefaultFunction ​

Usage Examples ​

Basic TypeScript Usage ​

Typed Script Results ​

Event Handler Typing ​

Custom Script Context ​

Generic Script Execution ​

Configuration with Type Safety ​

Type Declarations ​

Advanced Type Patterns ​

Script Factory Pattern ​

Event-Driven Architecture ​

Related Documentation ​

TypeScript Types

Core Types

`createScriptRunner`

Configuration Types

`CreateScriptRunnerOptions`

`RunnerConfig`

`EffectiveConfig`

Script Runner Instance Types

`ScriptRunnerInstance`

`ExecutionParams`

`ScriptExecutionResult`

`LoggerFunction`

Script Types

`ScriptModule`

`ScriptContext`

`ColoredConsole`

Event System Types

`ScriptEventHandler`

Console Interception Types

`ConsoleInterceptionOptions`

`ScriptExecutorOptions`

Utility Types

`EventEmitterMethods`

`PartialConfig`

Type Guards

`isScriptModule`

`hasExecuteFunction`

`hasDefaultFunction`

Usage Examples

Basic TypeScript Usage

Typed Script Results

Event Handler Typing

Custom Script Context

Generic Script Execution

Configuration with Type Safety

Type Declarations

Advanced Type Patterns

Script Factory Pattern

Event-Driven Architecture

Related Documentation