import { CollectionSchemaBase } from './dsl.js';

// Task definitions: scheduled (timer) operations — the second member of the
// action closure (action = controller | task | third callback).
//
// A task is a contract: name + cron + what it does. It declares NO state
// changes — state changes are expressed by journey steps. Task implementation
// (scan logic, idempotency) lives in the implementation layer (e.g. pylon-flow
// steps).
//
// Task represents ONLY timers (cron-driven). Async/event-driven operations
// belong to the event system (EventObserver / EventNotifier, pending), not
// here.

export interface TaskSchema extends CollectionSchemaBase {
  type: 'task';
  /** Display label (Chinese) for the task. */
  label: string;
  /** Cron expression — the timer schedule. */
  cron: string;
}

/**
 * Defines a scheduled task. `name` must end with 'Task' (PascalCase,
 * e.g. 'AutoRefundTask'); the export symbol equals the name. File name is the
 * name minus the Task suffix, kebab-cased, plus '.task.ts'
 * (AutoRefundTask → task_schema/auto-refund.task.ts).
 */
export function defineTask(options: {
  name: string;
  label: string;
  cron: string;
  description?: string;
}): TaskSchema {
  if (!/(Task)$/.test(options.name)) {
    throw new Error(
      `task ${options.name}: name must end with 'Task' (PascalCase, e.g. 'AutoRefundTask')`,
    );
  }
  if (!options.cron || options.cron.trim() === '') {
    throw new Error(
      `task ${options.name}: cron is required (a task is a timer)`,
    );
  }
  return {
    type: 'task',
    name: options.name,
    label: options.label,
    description: options.description,
    cron: options.cron,
  };
}