@pikku/core 0.12.142 → 0.12.144

package/dist/wirings/workflow/workflow-unwind-plan.js

@@ -1,9 +1,4 @@
-import { isCompensationStepName, isMilestoneStepName, } from './workflow-constants.js';
-const IN_FLIGHT = new Set([
-    'pending',
-    'scheduled',
-    'running',
-]);
+import { isCompensationStepName, isMilestoneStepName, STEP_IN_FLIGHT_STATES, } from './workflow-constants.js';
 const startedAt = (record) => record.createdAt.getTime();
 const finishedAt = (record) => (record.succeededAt ?? record.failedAt ?? record.updatedAt).getTime();
 export function planUnwind(input) {
@@ -16,7 +11,7 @@ export function planUnwind(input) {
         .sort((a, b) => finishedAt(b) - finishedAt(a) ||
         input.records.indexOf(b) - input.records.indexOf(a));
     const lastMilestone = milestones[0];
-    const forwardInFlight = forward.some((r) => IN_FLIGHT.has(r.status) && input.hasCompensation(r));
+    const forwardInFlight = forward.some((r) => STEP_IN_FLIGHT_STATES.has(r.status) && input.hasCompensation(r));
     let candidates = forward.filter((r) => {
         if (!r.rpcName || input.skip.has(r.stepName))
             return false;

package/dist/wirings/workflow/workflow.types.d.ts

@@ -6,6 +6,10 @@ import type { LeaseService } from '../../services/lease-service.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, MilestoneStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
+/**
+ * How a run was started: the wire type, the parent run and step for a child
+ * workflow, and the user whose session started it — who becomes its owner.
+ */
 export interface WorkflowRunWire {
     type: string;
     id?: string;
@@ -13,6 +17,9 @@ export interface WorkflowRunWire {
     parentStepId?: string;
     pikkuUserId?: string;
 }
+/**
+ * The resolved `workflow` section of the app config: default retries and the queue names the engine uses.
+ */
 export interface WorkflowServiceConfig {
     retries: number;
     retryDelay: number;
@@ -20,6 +27,13 @@ export interface WorkflowServiceConfig {
     stepWorkerQueueName: string;
     sleeperRPCName: string;
 }
+/**
+ * How a workflow service routes its jobs. `per-workflow` (the default) uses a
+ * workflow's dedicated queue when one is declared; `shared-groups` sends every
+ * job through the shared queues, grouped by workflow, with
+ * `queueGroupConcurrency` (default 2) per group. `queueConcurrency` defaults
+ * to 20.
+ */
 export interface WorkflowQueueOptions {
     queueStrategy?: 'per-workflow' | 'shared-groups';
     queueConcurrency?: number;
@@ -34,13 +48,20 @@ export interface WorkflowQueueOptions {
 export interface WorkflowServiceOptions extends WorkflowQueueOptions {
     leaseService: LeaseService;
 }
+/** A step a deterministic workflow is known to run, before it runs. */
 export interface WorkflowPlannedStep {
     stepName: string;
     displayName?: string;
 }
+/**
+ * Where a run stands. `compensating` and the two after it belong to a saga unwinding after a failure.
+ */
 export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled' | 'compensating' | 'compensated' | 'compensation_failed';
+/** Whether a recorded version of a workflow's graph may be run. */
 export type WorkflowVersionStatus = 'draft' | 'active' | 'declined';
+/** Where one step attempt stands. */
 export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended';
+/** One stored workflow run. */
 export interface WorkflowRun {
     id: string;
     workflow: string;
@@ -56,6 +77,7 @@ export interface WorkflowRun {
     createdAt: Date;
     updatedAt: Date;
 }
+/** One stored attempt at a workflow step. */
 export interface StepState {
     stepId: string;
     status: StepStatus;
@@ -89,6 +111,7 @@ export interface StepState {
     succeededAt?: Date;
     failedAt?: Date;
 }
+/** A run summarised for display: status, steps and outcome. */
 export interface WorkflowRunStatus {
     id: string;
     status: WorkflowStatus;
@@ -112,6 +135,11 @@ export interface WorkflowRunStatus {
         error: string;
     }>;
 }
+/**
+ * Read and delete access to stored workflow runs, for consoles and status
+ * routes. It applies no ownership check of its own: callers that expose it to
+ * users check with `assertWorkflowRunOwner` first.
+ */
 export interface WorkflowRunService {
     listRuns(options?: {
         workflowName?: string;
@@ -135,6 +163,11 @@ export interface WorkflowRunService {
     } | null>;
     deleteRun(id: string): Promise<boolean>;
 }
+/**
+ * A secondary store that receives a copy of every write a workflow service
+ * makes — for reporting or a console database. A failed mirror write is logged
+ * and ignored, and the engine never reads from it.
+ */
 export interface WorkflowRunMirror {
     createRun(runId: string, workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
@@ -159,12 +192,14 @@ export interface WorkflowRunMirror {
     upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
     updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
 }
+/** A registered workflow: its name and the function that runs it. */
 export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
     name: string;
     func: PikkuFunctionConfig;
     middleware?: PikkuFunctionConfig['middleware'];
     tags?: string[];
 };
+/** Start, read and cancel runs of one workflow. */
 export interface PikkuWorkflow {
     start: <I>(input: I) => Promise<{
         runId: string;
@@ -172,12 +207,15 @@ export interface PikkuWorkflow {
     getRun: (runId: string) => Promise<WorkflowRun>;
     cancelRun: (runId: string) => Promise<void>;
 }
+/** One declared workflow context variable: its type, default and description. */
 export interface ContextVariable {
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
     default?: unknown;
     description?: string;
 }
+/** A workflow's declared context variables, keyed by name. */
 export type WorkflowContext = Record<string, ContextVariable>;
+/** Generated metadata for every workflow, keyed by name. */
 export type WorkflowsMeta = Record<string, CommonWireMeta & {
     name: string;
     steps: WorkflowStepMeta[];
@@ -195,6 +233,7 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     skip?: string;
     virtualUsers?: string[];
 }>;
+/** The slice of a workflow's generated metadata the engine needs at run time. */
 export interface WorkflowRuntimeMeta {
     name: string;
     pikkuFuncId: string;
@@ -208,4 +247,5 @@ export interface WorkflowRuntimeMeta {
     deterministic?: boolean;
     plannedSteps?: WorkflowPlannedStep[];
 }
+/** Runtime workflow metadata, keyed by name. */
 export type WorkflowsRuntimeMeta = Record<string, WorkflowRuntimeMeta>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.142",
+  "version": "0.12.144",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -12,14 +12,15 @@
   "type": "module",
   "scripts": {
     "tsc": "tsc && tsc -p tsconfig.type-tests.json",
-    "build": "tsc -b",
+    "build": "bun run clean && tsc -b",
     "ncu": "npx npm-check-updates",
     "release": "npm run build && npm test",
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
     "prepublishOnly": "bun run build",
-    "api-report": "tsx scripts/generate-api-report.mts"
+    "api-report": "tsx scripts/generate-api-report.mts",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "sideEffects": [
     "./dist/errors/errors.js",
@@ -31,6 +32,7 @@
     "./dist/wirings/workflow/workflow-errors.js",
     "./dist/wirings/workflow/workflow-run-ownership.js"
   ],
+  "types": "./dist/bootstrap-compat/root.d.ts",
   "exports": {
     ".": "./dist/bootstrap-compat/root.js",
     "./types": "./dist/types/index.js",
@@ -75,6 +77,10 @@
     "./services": "./dist/services/index.js",
     "./flag": "./dist/wirings/flag/index.js",
     "./services/local-meta": "./dist/services/meta-service.js",
+    "./services/in-memory-queue": "./dist/wirings/queue/in-memory-queue-service.js",
+    "./services/in-memory-trigger": "./dist/wirings/trigger/in-memory-trigger-service.js",
+    "./services/in-memory-workflow": "./dist/wirings/workflow/in-memory-workflow-service.js",
+    "./services/local-gateway": "./dist/wirings/gateway/local-gateway-service.js",
     "./services/v8-coverage": "./dist/services/v8-coverage-service.js",
     "./services/istanbul-coverage": "./dist/services/istanbul-coverage-service.js",
     "./services/local-content": "./dist/services/local-content.js",
@@ -89,22 +95,33 @@
     "./lifecycle": "./dist/lifecycle.js",
     "./schema": "./dist/schema.js",
     "./testing": "./dist/testing/index.js",
-    "./dev": "./dist/dev/hot-reload.js"
+    "./dev": "./dist/dev/hot-reload.js",
+    "./package.json": "./package.json"
   },
+  "files": [
+    "dist"
+  ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@types/json-schema": "^7.0.15",
     "cookie": "^2.0.1",
-    "json-schema": "^0.4.0",
     "path-to-regexp": "^8.4.2",
     "picoquery": "^2.5.0"
   },
+  "peerDependencies": {
+    "esbuild": ">=0.28.2 <1"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@ag-ui/core": "0.0.57",
-    "@pikku/deploy": "^0.12.15",
-    "@types/node": "^24.13.3",
+    "@ag-ui/core": "0.0.59",
+    "@pikku/deploy": "^0.12.16",
+    "@types/node": "^26.6.5",
     "esbuild": "~0.28.2",
-    "tsx": "^4.23.12"
+    "tsx": "^4.23.15"
   },
   "engines": {
     "node": ">=24"