@dotdo/do 0.1.0

package/dist/db/collections/actions.d.ts

@@ -0,0 +1,440 @@
+/**
+ * Actions Collection - Durable action execution for Digital Objects
+ *
+ * @module collections/actions
+ *
+ * @description
+ * Manages durable Actions (instances of Verbs) within a Digital Object.
+ * Actions track the full lifecycle of operations from creation through completion,
+ * including retry handling, error tracking, and actor attribution.
+ *
+ * Action lifecycle:
+ * ```
+ * pending -> running -> completed
+ *                    -> failed -> retrying -> completed
+ *                             -> cancelled
+ *                    -> blocked (waiting on dependency)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const actions = new ActionCollection(storage, verbs)
+ *
+ * // Create an action
+ * const action = await actions.create({
+ *   verb: 'subscribe',
+ *   object: 'customer_123',
+ *   input: { plan: 'pro' },
+ *   actor: { type: 'User', id: 'user_456' }
+ * })
+ *
+ * // Start execution
+ * await actions.start(action.$id)
+ *
+ * // Complete with output
+ * await actions.complete(action.$id, { subscriptionId: 'sub_789' })
+ * ```
+ */
+import type { Action, ActionStatus, ActionRequest, Actor, ActorType } from '../../types/collections';
+import { BaseCollection, DOStorage } from './base';
+import type { VerbCollection } from './verbs';
+/**
+ * Options for creating an action
+ */
+export interface CreateActionOptions<TInput = unknown, TConfig = unknown> {
+    /**
+     * Verb reference (action type)
+     */
+    verb: string;
+    /**
+     * Subject (who/what performed the action, if different from actor)
+     */
+    subject?: string;
+    /**
+     * Object (what the action operates on)
+     */
+    object?: string;
+    /**
+     * Input data for the action
+     */
+    input?: TInput;
+    /**
+     * Configuration/options for the action
+     */
+    config?: TConfig;
+    /**
+     * Actor who initiated this action
+     */
+    actor: Actor;
+    /**
+     * Request that initiated this action (optional)
+     */
+    request?: ActionRequest;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for failing an action
+ */
+export interface FailActionOptions {
+    /**
+     * Error code
+     */
+    code: string;
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Stack trace (optional)
+     */
+    stack?: string;
+    /**
+     * Whether the action can be retried
+     */
+    retryable?: boolean;
+}
+/**
+ * Retry policy for actions
+ */
+export interface ActionRetryPolicy {
+    /**
+     * Maximum number of retry attempts
+     */
+    maxAttempts: number;
+    /**
+     * Initial delay in milliseconds
+     */
+    initialDelay: number;
+    /**
+     * Maximum delay in milliseconds
+     */
+    maxDelay: number;
+    /**
+     * Backoff multiplier
+     */
+    backoffMultiplier: number;
+}
+/**
+ * Default retry policy
+ */
+export declare const DEFAULT_RETRY_POLICY: ActionRetryPolicy;
+/**
+ * Actions collection for durable action execution
+ *
+ * @description
+ * The ActionCollection manages the lifecycle of durable actions within a DO.
+ * Every action is an instance of a Verb and tracks:
+ *
+ * - Who initiated it (Actor: User, Agent, Service, System)
+ * - What it operates on (subject, object)
+ * - Its current status and history
+ * - Input, config, and output data
+ * - Errors and retry information
+ *
+ * Actions are durable - they survive DO hibernation and can be resumed.
+ * This enables long-running operations, workflows, and reliable execution.
+ *
+ * @example
+ * ```typescript
+ * const actions = new ActionCollection(storage, verbs)
+ *
+ * // Create and execute an action
+ * const action = await actions.create({
+ *   verb: 'process',
+ *   object: 'order_123',
+ *   input: { priority: 'high' },
+ *   actor: { type: 'Service', id: 'payment-service' }
+ * })
+ *
+ * try {
+ *   await actions.start(action.$id)
+ *   const result = await processOrder(action.input)
+ *   await actions.complete(action.$id, result)
+ * } catch (error) {
+ *   await actions.fail(action.$id, {
+ *     code: 'PROCESS_ERROR',
+ *     message: error.message,
+ *     retryable: true
+ *   })
+ * }
+ *
+ * // Query actions
+ * const pending = await actions.findByStatus('pending')
+ * const userActions = await actions.findByActor('User', 'user_123')
+ * ```
+ */
+export declare class ActionCollection extends BaseCollection<any> {
+    /**
+     * Reference to verb collection for type validation
+     */
+    private readonly verbs;
+    /**
+     * Default retry policy
+     */
+    private readonly retryPolicy;
+    /**
+     * Create a new ActionCollection instance
+     *
+     * @param storage - DO storage interface
+     * @param verbs - Verb collection for type validation
+     * @param retryPolicy - Optional custom retry policy
+     */
+    constructor(storage: DOStorage, verbs: VerbCollection, retryPolicy?: ActionRetryPolicy);
+    /**
+     * Initialize the actions table in SQLite
+     *
+     * @internal
+     */
+    protected initializeTable(): Promise<void>;
+    /**
+     * Create a new action
+     *
+     * @param data - Action creation options
+     * @returns Created action with generated ID and pending status
+     *
+     * @throws {ValidationError} If verb is not registered
+     *
+     * @example
+     * ```typescript
+     * const action = await actions.create({
+     *   verb: 'approve',
+     *   object: 'request_123',
+     *   actor: { type: 'User', id: 'user_456', name: 'John' }
+     * })
+     * console.log(action.status) // 'pending'
+     * ```
+     */
+    create<TInput = unknown, TConfig = unknown>(data: CreateActionOptions<TInput, TConfig>): Promise<Action<TInput, unknown, TConfig>>;
+    /**
+     * Start action execution
+     *
+     * @param id - Action ID
+     * @returns Updated action with 'running' status
+     *
+     * @throws {NotFoundError} If action not found
+     * @throws {ValidationError} If action is not in 'pending' or 'retrying' status
+     *
+     * @example
+     * ```typescript
+     * const action = await actions.start('action_123')
+     * console.log(action.status) // 'running'
+     * console.log(action.startedAt) // timestamp
+     * ```
+     */
+    start(id: string): Promise<Action>;
+    /**
+     * Complete action successfully
+     *
+     * @param id - Action ID
+     * @param output - Output data from action execution
+     * @returns Updated action with 'completed' status
+     *
+     * @throws {NotFoundError} If action not found
+     * @throws {ValidationError} If action is not in 'running' status
+     *
+     * @example
+     * ```typescript
+     * const action = await actions.complete('action_123', {
+     *   subscriptionId: 'sub_789',
+     *   activatedAt: Date.now()
+     * })
+     * console.log(action.status) // 'completed'
+     * ```
+     */
+    complete<TOutput = unknown>(id: string, output?: TOutput): Promise<Action>;
+    /**
+     * Fail action with error
+     *
+     * @param id - Action ID
+     * @param error - Error details
+     * @returns Updated action with 'failed' or 'retrying' status
+     *
+     * @throws {NotFoundError} If action not found
+     * @throws {ValidationError} If action is not in 'running' status
+     *
+     * @description
+     * If the error is retryable and retry attempts remain, status becomes 'retrying'.
+     * Otherwise, status becomes 'failed'.
+     *
+     * @example
+     * ```typescript
+     * const action = await actions.fail('action_123', {
+     *   code: 'PAYMENT_DECLINED',
+     *   message: 'Card declined',
+     *   retryable: true
+     * })
+     * console.log(action.status) // 'retrying' or 'failed'
+     * ```
+     */
+    fail(id: string, error: FailActionOptions): Promise<Action>;
+    /**
+     * Cancel an action
+     *
+     * @param id - Action ID
+     * @param reason - Optional cancellation reason
+     * @returns Updated action with 'cancelled' status
+     *
+     * @throws {NotFoundError} If action not found
+     * @throws {ValidationError} If action is already completed or failed
+     *
+     * @example
+     * ```typescript
+     * await actions.cancel('action_123', 'User requested cancellation')
+     * ```
+     */
+    cancel(id: string, reason?: string): Promise<Action>;
+    /**
+     * Block an action (waiting on dependency)
+     *
+     * @param id - Action ID
+     * @param dependency - ID of the blocking action or resource
+     * @returns Updated action with 'blocked' status
+     *
+     * @throws {NotFoundError} If action not found
+     *
+     * @example
+     * ```typescript
+     * // Block action until payment is processed
+     * await actions.block('action_123', 'action_payment_456')
+     * ```
+     */
+    block(id: string, dependency: string): Promise<Action>;
+    /**
+     * Unblock an action
+     *
+     * @param id - Action ID
+     * @returns Updated action with 'pending' status
+     *
+     * @throws {NotFoundError} If action not found
+     * @throws {ValidationError} If action is not blocked
+     */
+    unblock(id: string): Promise<Action>;
+    /**
+     * Get action by ID
+     *
+     * @param id - Action ID
+     * @returns Action or null if not found
+     */
+    get(id: string): Promise<Action | null>;
+    /**
+     * Find actions by status
+     *
+     * @param status - Action status to filter by
+     * @returns Array of matching actions
+     *
+     * @example
+     * ```typescript
+     * const pending = await actions.findByStatus('pending')
+     * const running = await actions.findByStatus('running')
+     * ```
+     */
+    findByStatus(status: ActionStatus): Promise<Action[]>;
+    /**
+     * Find actions by verb
+     *
+     * @param verb - Verb action form
+     * @returns Array of matching actions
+     *
+     * @example
+     * ```typescript
+     * const approvals = await actions.findByVerb('approve')
+     * ```
+     */
+    findByVerb(verb: string): Promise<Action[]>;
+    /**
+     * Find actions by actor
+     *
+     * @param actorType - Actor type (User, Agent, Service, System)
+     * @param actorId - Actor ID
+     * @returns Array of matching actions
+     *
+     * @example
+     * ```typescript
+     * const userActions = await actions.findByActor('User', 'user_123')
+     * const serviceActions = await actions.findByActor('Service', 'payment-service')
+     * ```
+     */
+    findByActor(actorType: ActorType, actorId: string): Promise<Action[]>;
+    /**
+     * Find actions by object
+     *
+     * @param object - Object ID
+     * @returns Array of actions on the object
+     *
+     * @example
+     * ```typescript
+     * const orderActions = await actions.findByObject('order_123')
+     * ```
+     */
+    findByObject(object: string): Promise<Action[]>;
+    /**
+     * Find retryable actions that are ready for retry
+     *
+     * @returns Actions in 'retrying' status ready for next attempt
+     *
+     * @description
+     * Calculates next retry time based on retry policy and returns
+     * actions that are past their retry delay.
+     */
+    findRetryable(): Promise<Action[]>;
+    /**
+     * Get pending actions count
+     *
+     * @returns Number of pending actions
+     */
+    getPendingCount(): Promise<number>;
+    /**
+     * Get running actions count
+     *
+     * @returns Number of running actions
+     */
+    getRunningCount(): Promise<number>;
+    /**
+     * Calculate next retry delay
+     *
+     * @param retryCount - Current retry count
+     * @returns Delay in milliseconds
+     *
+     * @internal
+     */
+    calculateRetryDelay(retryCount: number): number;
+    /**
+     * Check if action can be retried
+     *
+     * @param action - Action to check
+     * @returns True if retry is possible
+     *
+     * @internal
+     */
+    canRetry(action: Action): boolean;
+    /**
+     * Get action statistics
+     *
+     * @returns Count of actions by status
+     *
+     * @example
+     * ```typescript
+     * const stats = await actions.getStats()
+     * // { pending: 5, running: 2, completed: 100, failed: 3 }
+     * ```
+     */
+    getStats(): Promise<Record<ActionStatus, number>>;
+    /**
+     * Clean up old completed/failed actions
+     *
+     * @param olderThan - Delete actions older than this timestamp
+     * @returns Number of deleted actions
+     *
+     * @example
+     * ```typescript
+     * // Delete completed actions older than 30 days
+     * const deleted = await actions.cleanup(Date.now() - 30 * 24 * 60 * 60 * 1000)
+     * ```
+     */
+    cleanup(olderThan: number): Promise<number>;
+}
+export default ActionCollection;
+//# sourceMappingURL=actions.d.ts.map

package/dist/db/collections/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../db/collections/actions.ts"],"names":[],"mappings":"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"}