@pikku/core 0.11.0 → 0.11.2

package/src/wirings/scheduler/scheduler-runner.ts

@@ -1,18 +1,16 @@
 import {
-  PikkuInteraction,
-  PikkuWiringTypes,
+  PikkuWire,
   type CoreServices,
   type CoreSingletonServices,
   type CoreUserSession,
-  type CreateSessionServices,
+  type CreateWireServices,
 } from '../../types/core.types.js'
 import type { CoreScheduledTask } from './scheduler.types.js'
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
-import { closeSessionServices } from '../../utils.js'
+import { closeWireServices } from '../../utils.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { rpcService } from '../rpc/rpc-runner.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
+import { PikkuSessionService } from '../../services/user-session-service.js'
 import {
   CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
@@ -22,7 +20,7 @@ export type RunScheduledTasksParams = {
   name: string
   session?: CoreUserSession
   singletonServices: CoreSingletonServices
-  createSessionServices?: CreateSessionServices<
+  createWireServices?: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -36,7 +34,7 @@ export const wireScheduler = <
 >(
   scheduledTask: CoreScheduledTask<PikkuFunctionConfig>
 ) => {
-  const meta = pikkuState('scheduler', 'meta')
+  const meta = pikkuState(null, 'scheduler', 'meta')
   const taskMeta = meta[scheduledTask.name]
   if (!taskMeta) {
     throw new Error('Task metadata not found')
@@ -45,12 +43,11 @@ export const wireScheduler = <
     func: scheduledTask.func.func,
     auth: scheduledTask.func.auth,
     permissions: scheduledTask.func.permissions,
-    middleware: scheduledTask.func.middleware as any,
+    middleware: scheduledTask.func.middleware,
     tags: scheduledTask.func.tags,
-    docs: scheduledTask.func.docs as any,
   })
 
-  const tasks = pikkuState('scheduler', 'tasks')
+  const tasks = pikkuState(null, 'scheduler', 'tasks')
   if (tasks.has(scheduledTask.name)) {
     throw new Error(`Scheduled task already exists: ${scheduledTask.name}`)
   }
@@ -76,13 +73,13 @@ export async function runScheduledTask({
   name,
   session,
   singletonServices,
-  createSessionServices,
+  createWireServices,
 }: RunScheduledTasksParams): Promise<void> {
-  let sessionServices: any
-  const task = pikkuState('scheduler', 'tasks').get(name)
-  const meta = pikkuState('scheduler', 'meta')[name]
+  let wireServices: any
+  const task = pikkuState(null, 'scheduler', 'tasks').get(name)
+  const meta = pikkuState(null, 'scheduler', 'meta')[name]
 
-  const userSession = new PikkuUserSessionService()
+  const userSession = new PikkuSessionService()
   if (session) {
     userSession.set(session)
   }
@@ -96,8 +93,8 @@ export async function runScheduledTask({
     )
   }
 
-  // Create the scheduled task interaction object
-  const interaction: PikkuInteraction = {
+  // Create the scheduled task wire object
+  const wire: PikkuWire = {
     scheduledTask: {
       name,
       schedule: task.schedule,
@@ -106,6 +103,7 @@ export async function runScheduledTask({
         throw new ScheduledTaskSkippedError(name, reason)
       },
     },
+    session: userSession,
   }
 
   try {
@@ -113,40 +111,16 @@ export async function runScheduledTask({
       `Running schedule task: ${name} | schedule: ${task.schedule}`
     )
 
-    const getAllServices = async () => {
-      sessionServices = await createSessionServices?.(
-        singletonServices,
-        interaction,
-        session
-      )
-
-      return rpcService.injectRPCService(
-        {
-          ...singletonServices,
-          ...sessionServices,
-        },
-        interaction
-      )
-    }
-
-    const result = await runPikkuFunc(
-      PikkuWiringTypes.scheduler,
-      meta.name,
-      meta.pikkuFuncName,
-      {
-        singletonServices,
-        getAllServices,
-        userSession,
-        auth: false,
-        data: () => undefined,
-        inheritedMiddleware: meta.middleware,
-        wireMiddleware: task.middleware,
-        tags: task.tags,
-        interaction,
-      }
-    )
-
-    return result
+    await runPikkuFunc('scheduler', meta.name, meta.pikkuFuncName, {
+      singletonServices,
+      createWireServices,
+      auth: false,
+      data: () => undefined,
+      inheritedMiddleware: meta.middleware,
+      wireMiddleware: task.middleware,
+      tags: task.tags,
+      wire,
+    })
   } catch (e: any) {
     const errorResponse = getErrorResponse(e)
     if (errorResponse != null) {
@@ -154,12 +128,12 @@ export async function runScheduledTask({
     }
     throw e
   } finally {
-    if (sessionServices) {
-      await closeSessionServices(singletonServices.logger, sessionServices)
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
     }
   }
 }
 
 export const getScheduledTasks = () => {
-  return pikkuState('scheduler', 'tasks')
+  return pikkuState(null, 'scheduler', 'tasks')
 }

package/src/wirings/scheduler/scheduler.types.ts

@@ -1,8 +1,7 @@
 import {
-  PikkuDocs,
   CoreUserSession,
   CorePikkuMiddleware,
-  MiddlewareMetadata,
+  CommonWireMeta,
 } from '../../types/core.types.js'
 import {
   CorePikkuFunctionConfig,
@@ -15,14 +14,10 @@ import {
 export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
   Record<
     string,
-    {
-      pikkuFuncName: string
+    CommonWireMeta & {
       name: string
       schedule: string
       session?: UserSession
-      docs?: PikkuDocs
-      tags?: string[]
-      middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
     }
   >
 
@@ -38,13 +33,12 @@ export type CoreScheduledTask<
   name: string
   schedule: string
   func: PikkuFunctionConfig
-  docs?: PikkuDocs
   tags?: string[]
   middleware?: PikkuMiddleware[]
 }
 
 /**
- * Represents a scheduled task interaction object for middleware
+ * Represents a scheduled task wire object for middleware
  * Provides information about the current scheduled task execution
  */
 export interface PikkuScheduledTask {

package/src/wirings/trigger/index.ts

@@ -0,0 +1,2 @@
+export * from './trigger.types.js'
+export * from './trigger-runner.js'

package/src/wirings/trigger/trigger-runner.ts

@@ -0,0 +1,96 @@
+import type { CoreSingletonServices } from '../../types/core.types.js'
+import type { CoreTrigger, TriggerInstance } from './trigger.types.js'
+import { pikkuState } from '../../pikku-state.js'
+import type { CorePikkuTriggerFunctionConfig } from '../../function/functions.types.js'
+
+/**
+ * Registers a trigger with the Pikku framework.
+ * The trigger will be available for setup via setupTrigger.
+ */
+export const wireTrigger = <
+  TConfig = unknown,
+  TOutput = unknown,
+  TriggerFunctionConfig extends CorePikkuTriggerFunctionConfig<
+    TConfig,
+    TOutput
+  > = CorePikkuTriggerFunctionConfig<TConfig, TOutput>,
+>(
+  trigger: CoreTrigger<TConfig, TOutput, TriggerFunctionConfig>
+) => {
+  const meta = pikkuState(null, 'trigger', 'meta')
+  const triggerMeta = meta[trigger.name]
+  if (!triggerMeta) {
+    throw new Error(`Trigger metadata not found: ${trigger.name}`)
+  }
+
+  const triggers = pikkuState(null, 'trigger', 'triggers')
+  if (triggers.has(trigger.name)) {
+    throw new Error(`Trigger already exists: ${trigger.name}`)
+  }
+  triggers.set(trigger.name, trigger as any)
+}
+
+/**
+ * Parameters for setting up a trigger
+ */
+export type SetupTriggerParams<TOutput = unknown> = {
+  name: string
+  singletonServices: CoreSingletonServices
+  onTrigger: (data: TOutput) => void | Promise<void>
+}
+
+/**
+ * Sets up a registered trigger and starts listening for events.
+ * Returns a TriggerInstance with a teardown function.
+ */
+export async function setupTrigger<TOutput = unknown>({
+  name,
+  singletonServices,
+  onTrigger,
+}: SetupTriggerParams<TOutput>): Promise<TriggerInstance> {
+  const trigger = pikkuState(null, 'trigger', 'triggers').get(name)
+  const meta = pikkuState(null, 'trigger', 'meta')[name]
+
+  if (!trigger) {
+    throw new Error(`Trigger not found: ${name}`)
+  }
+  if (!meta) {
+    throw new Error(`Trigger metadata not found: ${name}`)
+  }
+
+  const wire = {
+    trigger: {
+      trigger: (data: TOutput) => {
+        singletonServices.logger.info(`Trigger fired: ${name}`)
+        onTrigger(data)
+      },
+    },
+  }
+
+  singletonServices.logger.info(`Setting up trigger: ${name}`)
+
+  const teardown = await trigger.func.func(
+    singletonServices,
+    trigger.config,
+    wire as any
+  )
+
+  return {
+    name,
+    teardown,
+  }
+}
+
+/**
+ * Gets all registered triggers
+ */
+export const getRegisteredTriggers = () => {
+  return pikkuState(null, 'trigger', 'triggers')
+}
+
+/**
+ * Gets trigger metadata
+ */
+export const getTriggerMeta = () => {
+  return pikkuState(null, 'trigger', 'meta')
+}

package/src/wirings/trigger/trigger.types.ts

@@ -0,0 +1,56 @@
+import type { CorePikkuTriggerFunctionConfig } from '../../function/functions.types.js'
+
+/**
+ * The trigger interaction object passed to trigger functions via the wire.
+ * Call trigger() to fire the trigger and start a new workflow/execution.
+ */
+export interface PikkuTrigger<TOutput = unknown> {
+  trigger: (data: TOutput) => void
+}
+
+/**
+ * Metadata for registered triggers stored in state.
+ */
+export type TriggerMeta = Record<
+  string,
+  {
+    pikkuFuncName: string
+    name: string
+    description?: string
+    tags?: string[]
+  }
+>
+
+/**
+ * Core trigger definition for registration.
+ *
+ * @template TConfig - Configuration type
+ * @template TOutput - Output type
+ */
+export interface CoreTrigger<
+  TConfig = unknown,
+  TOutput = unknown,
+  TriggerFunctionConfig extends CorePikkuTriggerFunctionConfig<
+    TConfig,
+    TOutput
+  > = CorePikkuTriggerFunctionConfig<TConfig, TOutput>,
+> {
+  /** Unique name for this trigger */
+  name: string
+  /** The trigger function configuration */
+  func: TriggerFunctionConfig
+  /** Configuration to pass to the trigger function */
+  config: TConfig
+  /** Optional description */
+  description?: string
+  /** Optional tags for categorization */
+  tags?: string[]
+}
+
+/**
+ * Represents a trigger instance with teardown capability
+ */
+export interface TriggerInstance {
+  name: string
+  teardown: () => void | Promise<void>
+}

package/src/wirings/workflow/dsl/index.ts

@@ -0,0 +1,30 @@
+/**
+ * DSL (Domain Specific Language) workflow exports
+ */
+export { addWorkflow } from './workflow-runner.js'
+
+export type {
+  WorkflowStepOptions,
+  WorkflowWireDoRPC,
+  WorkflowWireDoInline,
+  WorkflowWireSleep,
+  InputSource,
+  OutputBinding,
+  RpcStepMeta,
+  SimpleCondition,
+  Condition,
+  BranchStepMeta,
+  ParallelGroupStepMeta,
+  FanoutStepMeta,
+  ReturnStepMeta,
+  InlineStepMeta,
+  SleepStepMeta,
+  CancelStepMeta,
+  SwitchCaseMeta,
+  SwitchStepMeta,
+  FilterStepMeta,
+  ArrayPredicateStepMeta,
+  WorkflowStepMeta,
+  WorkflowStepWire,
+  PikkuWorkflowWire,
+} from './workflow-dsl.types.js'

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -0,0 +1,312 @@
+/**
+ * DSL (Domain Specific Language) workflow types
+ * These types define the step-based workflow format extracted by the inspector
+ */
+
+import type { WorkflowRun } from '../workflow.types.js'
+
+/**
+ * Workflow step options
+ */
+export interface WorkflowStepOptions {
+  /** Display name for logs/UI (optional, doesn't affect execution) */
+  description?: string
+  /** Number of retry attempts for failed steps (only applies to local execution) */
+  retries?: number
+  /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
+  retryDelay?: string | number
+  // Future: timeout, failFast, priority
+}
+
+/**
+ * Type signature for workflow.do() RPC form - used by inspector
+ */
+export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(
+  stepName: string,
+  rpcName: string,
+  data: TInput,
+  options?: WorkflowStepOptions
+) => Promise<TOutput>
+
+/**
+ * Type signature for workflow.do() inline form - used by inspector
+ */
+export type WorkflowWireDoInline = <T>(
+  stepName: string,
+  fn: () => Promise<T> | T,
+  options?: WorkflowStepOptions
+) => Promise<T>
+
+/**
+ * Type signature for workflow.sleep() - used by inspector
+ */
+export type WorkflowWireSleep = (
+  stepName: string,
+  duration: string
+) => Promise<void>
+
+/**
+ * Input source for step arguments in DSL workflows
+ */
+export type InputSource =
+  | { from: 'input'; path: string }
+  | { from: 'outputVar'; name: string; path?: string }
+  | { from: 'item'; path: string }
+  | { from: 'literal'; value: unknown }
+  | { from: 'template'; parts: string[]; expressions: InputSource[] }
+
+/**
+ * Output binding for return statements in DSL workflows
+ */
+export type OutputBinding =
+  | { from: 'outputVar'; name: string; path?: string }
+  | { from: 'stateVar'; name: string; path?: string }
+  | { from: 'input'; path: string }
+  | { from: 'literal'; value: unknown }
+  | { from: 'expression'; expression: string }
+
+/**
+ * RPC step metadata (base form)
+ */
+export interface RpcStepMeta {
+  /** RPC form - generates queue worker */
+  type: 'rpc'
+  /** Cache key (stepName from workflow.do) */
+  stepName: string
+  /** RPC to invoke */
+  rpcName: string
+  /** Output variable name (if assigned) */
+  outputVar?: string
+  /** Input source mappings, or 'passthrough' when entire data is passed */
+  inputs?: Record<string, InputSource> | 'passthrough'
+  /** Step options */
+  options?: WorkflowStepOptions
+}
+
+/**
+ * Simple condition expression (leaf node)
+ */
+export interface SimpleCondition {
+  type: 'simple'
+  expression: string
+}
+
+/**
+ * Nested condition structure supporting AND/OR operations
+ */
+export type Condition =
+  | SimpleCondition
+  | { type: 'and'; conditions: Condition[] }
+  | { type: 'or'; conditions: Condition[] }
+
+/**
+ * A single branch in an if/else-if chain
+ */
+export interface BranchCase {
+  /** Condition for this branch */
+  condition: Condition
+  /** Steps to execute when condition is true */
+  steps: WorkflowStepMeta[]
+}
+
+/**
+ * Branch step metadata (if/else-if/else control flow)
+ */
+export interface BranchStepMeta {
+  type: 'branch'
+  /** Branches in order: first is "if", rest are "else if" */
+  branches: BranchCase[]
+  /** Else branch steps (when no conditions match) */
+  elseSteps?: WorkflowStepMeta[]
+}
+
+/**
+ * Parallel group step metadata (Promise.all with multiple steps)
+ */
+export interface ParallelGroupStepMeta {
+  type: 'parallel'
+  /** Child steps to execute in parallel */
+  children: RpcStepMeta[]
+}
+
+/**
+ * Fanout step metadata (parallel or sequential iteration)
+ */
+export interface FanoutStepMeta {
+  type: 'fanout'
+  /** Step name for this fanout */
+  stepName: string
+  /** Source array variable name */
+  sourceVar: string
+  /** Iterator variable name */
+  itemVar: string
+  /** Execution mode */
+  mode: 'parallel' | 'sequential'
+  /** Child step to execute per iteration */
+  child: RpcStepMeta
+  /** Time between iterations (sequential mode only) */
+  timeBetween?: string
+}
+
+/**
+ * Return step metadata (workflow output)
+ */
+export interface ReturnStepMeta {
+  type: 'return'
+  /** Output bindings */
+  outputs: Record<string, OutputBinding>
+}
+
+/**
+ * Inline step metadata (legacy support)
+ */
+export interface InlineStepMeta {
+  /** Inline form - local execution */
+  type: 'inline'
+  /** Cache key (stepName from workflow.do) */
+  stepName: string
+  /** Display name */
+  description?: string
+  /** Step options */
+  options?: WorkflowStepOptions
+}
+
+/**
+ * Sleep step metadata
+ */
+export interface SleepStepMeta {
+  /** Sleep step */
+  type: 'sleep'
+  /** Cache key (stepName from workflow.sleep) */
+  stepName: string
+  /** Sleep duration */
+  duration: string | number
+}
+
+/**
+ * Cancel step metadata
+ */
+export interface CancelStepMeta {
+  /** Cancel step */
+  type: 'cancel'
+  /** Optional cancellation reason */
+  reason?: string
+}
+
+/**
+ * Set step metadata (context variable assignment)
+ */
+export interface SetStepMeta {
+  /** Set step */
+  type: 'set'
+  /** Variable name to set (must be in context) */
+  variable: string
+  /** Value to assign (literal or expression) */
+  value: unknown
+}
+
+/**
+ * Switch case metadata
+ */
+export interface SwitchCaseMeta {
+  /** Case value (literal) or expression */
+  value?: string | number | boolean | null
+  /** Case expression (for complex cases) */
+  expression?: string
+  /** Steps to execute for this case */
+  steps: WorkflowStepMeta[]
+}
+
+/**
+ * Switch step metadata (switch/case control flow)
+ */
+export interface SwitchStepMeta {
+  type: 'switch'
+  /** Expression being switched on */
+  expression: string
+  /** Case branches */
+  cases: SwitchCaseMeta[]
+  /** Default case steps (optional) */
+  defaultSteps?: WorkflowStepMeta[]
+}
+
+/**
+ * Filter step metadata (array.filter)
+ */
+export interface FilterStepMeta {
+  type: 'filter'
+  /** Source array variable name */
+  sourceVar: string
+  /** Iterator variable name */
+  itemVar: string
+  /** Filter condition */
+  condition: Condition
+  /** Output variable name (if assigned) */
+  outputVar?: string
+}
+
+/**
+ * Array predicate step metadata (array.some, array.every)
+ */
+export interface ArrayPredicateStepMeta {
+  type: 'arrayPredicate'
+  /** Predicate mode */
+  mode: 'some' | 'every'
+  /** Source array variable name */
+  sourceVar: string
+  /** Iterator variable name */
+  itemVar: string
+  /** Predicate condition */
+  condition: Condition
+  /** Output variable name (if assigned) */
+  outputVar?: string
+}
+
+/**
+ * Workflow step metadata (extracted by inspector)
+ */
+export type WorkflowStepMeta =
+  | RpcStepMeta
+  | BranchStepMeta
+  | ParallelGroupStepMeta
+  | FanoutStepMeta
+  | ReturnStepMeta
+  | InlineStepMeta
+  | SleepStepMeta
+  | CancelStepMeta
+  | SwitchStepMeta
+  | FilterStepMeta
+  | ArrayPredicateStepMeta
+  | SetStepMeta
+
+/**
+ * Workflow step wire context for RPC functions
+ * Provides step-level metadata including retry attempt tracking
+ */
+export interface WorkflowStepWire {
+  /** The workflow run ID */
+  runId: string
+  /** The unique step ID */
+  stepId: string
+  /** Current attempt number (1-indexed, increments on retry) */
+  attemptCount: number
+}
+
+/**
+ * Workflow wire object for DSL workflows
+ * Provides workflow-specific capabilities to function execution
+ */
+export interface PikkuWorkflowWire {
+  /** The workflow name */
+  workflowName: string
+  /** The current run ID */
+  runId: string
+  /** Get the current workflow run */
+  getRun: () => Promise<WorkflowRun>
+
+  /** Execute a workflow step (overloaded - RPC or inline form) */
+  do: WorkflowWireDoRPC & WorkflowWireDoInline
+
+  /** Sleep for a duration */
+  sleep: WorkflowWireSleep
+}