@nanobpm/urban 0.13.0 → 0.14.0

package/dist/runtime/core/host.d.ts

@@ -74,13 +74,17 @@ export interface HostContext {
     /** Structured log sink. */
     log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
-/** A job handed to a worker handler, plus the ack/fail callbacks. */
-export interface EngineJob {
+/** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
+ *  variables carried on the job; it defaults to an open record when a handler doesn't
+ *  declare a concrete input shape. The `object` bound (rather than `Record<string, unknown>`)
+ *  lets plain `interface` shapes be used as `In` — interfaces lack the implicit index
+ *  signature that a `Record` bound would demand. */
+export interface EngineJob<In extends object = Record<string, unknown>> {
     jobKey: string;
     jobType: string;
     processInstanceKey?: string;
     elementId?: string;
-    variables: Record<string, unknown>;
+    variables: In;
 }
 export type JobHandler = (job: EngineJob) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 /** A registered worker subscription. */

package/dist/runtime/core/modules/workers.d.ts

@@ -6,8 +6,23 @@ import { type DecisionEvaluator } from "./llm.ts";
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
  *  "is not a function" / `JSON.parse` error. */
 export declare function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator;
-/** A handler as authored by an app: the job plus the injected app API. */
-export type AppJobHandler = (job: EngineJob, app: AppApi) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * A handler as authored by an app: the job plus the injected app API.
+ *
+ * Both type parameters are optional:
+ *   - `In`  types `job.variables` (the process variables the job carries).
+ *   - `Out` types the completion **variables map** the handler returns to the engine.
+ * Each defaults to an open `Record<string, unknown>`, so `AppJobHandler`,
+ * `AppJobHandler<In>`, and `AppJobHandler<In, Out>` are all valid.
+ *
+ * The bound is `extends object` (not `Record<string, unknown>`) so a plain `interface In {…}`
+ * / `interface Out {…}` can be supplied — interfaces have no implicit index signature and so
+ * don't satisfy a `Record` bound. The looser bound means `Out` is not *forced* to be a plain
+ * variables map at the type level; authors are expected to return a JSON-object of completion
+ * variables (not a `Date`, `Map`, array, etc.), which is what the engine sends on job
+ * completion. Both parameters are erased at runtime — they only shape authoring-time types.
+ */
+export type AppJobHandler<In extends object = Record<string, unknown>, Out extends object = Record<string, unknown>> = (job: EngineJob<In>, app: AppApi) => Promise<Out | void> | Out | void;
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",

package/src/runtime/core/host.ts

@@ -83,13 +83,17 @@ export interface HostContext {
   log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
 
-/** A job handed to a worker handler, plus the ack/fail callbacks. */
-export interface EngineJob {
+/** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
+ *  variables carried on the job; it defaults to an open record when a handler doesn't
+ *  declare a concrete input shape. The `object` bound (rather than `Record<string, unknown>`)
+ *  lets plain `interface` shapes be used as `In` — interfaces lack the implicit index
+ *  signature that a `Record` bound would demand. */
+export interface EngineJob<In extends object = Record<string, unknown>> {
   jobKey: string;
   jobType: string;
   processInstanceKey?: string;
   elementId?: string;
-  variables: Record<string, unknown>;
+  variables: In;
 }
 
 export type JobHandler = (

package/src/runtime/core/modules/workers.test.ts

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
-import { mountWorkers, sdkDecisionEvaluator } from "./workers.ts";
+import { mountWorkers, sdkDecisionEvaluator, type AppJobHandler } from "./workers.ts";
 
 /** A tiny engine that records registrations and can deliver a job to a handler. */
 class MiniEngine {
@@ -156,3 +156,55 @@ test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecis
   const evaluate = sdkDecisionEvaluator({});
   await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
 });
+
+// ── AppJobHandler generics: optional In/Out type parameters ──────────────────────────────
+// These are primarily compile-time assertions (the suite is typechecked by `tsc --noEmit`),
+// with a runtime smoke that a typed handler still returns its output when delivered a job.
+test("AppJobHandler carries optional In/Out variable types", async () => {
+  // `In` is a plain interface — the `object` bound (not `Record<string, unknown>`) makes this
+  // work, since interfaces have no implicit index signature.
+  interface In {
+    prKey: string;
+    round: number;
+    summary?: string;
+  }
+  interface Out {
+    ok: boolean;
+  }
+
+  // In + Out: job.variables is typed as In, the return must be Out (or void).
+  const typed: AppJobHandler<In, Out> = async (job) => {
+    const key: string = job.variables.prKey; // typed access compiles
+    const n: number = job.variables.round;
+    return { ok: key.length > 0 && n >= 0 };
+  };
+
+  // In only: Out defaults to an open variables map, so any plain object of completion
+  // variables may be returned.
+  const inOnly: AppJobHandler<In> = (job) => ({ echoed: job.variables.prKey });
+
+  // No parameters: fully open — the pre-generics behaviour.
+  const open: AppJobHandler = (job) => ({ count: Object.keys(job.variables).length });
+
+  // Returning nothing (void) is allowed under any parameterisation.
+  const voidReturn: AppJobHandler<In> = () => {};
+
+  const job: EngineJob<In> = {
+    jobKey: "1",
+    jobType: "pr.finalize",
+    variables: { prKey: "p1", round: 2 },
+  };
+  // The open handler defaults `In` to a record; interface-typed jobs aren't assignable to it,
+  // so hand it a plainly-typed job (the pre-generics shape).
+  const openJob: EngineJob = {
+    jobKey: "2",
+    jobType: "pr.finalize",
+    variables: { prKey: "p1", round: 2 },
+  };
+  const app = {} as AppApi;
+
+  assert.deepEqual(await typed(job, app), { ok: true });
+  assert.deepEqual(await inOnly(job, app), { echoed: "p1" });
+  assert.deepEqual(await open(openJob, app), { count: 2 });
+  assert.equal(await voidReturn(job, app), undefined);
+});

package/src/runtime/core/modules/workers.ts

@@ -42,11 +42,26 @@ export function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator {
   };
 }
 
-/** A handler as authored by an app: the job plus the injected app API. */
-export type AppJobHandler = (
-  job: EngineJob,
+/**
+ * A handler as authored by an app: the job plus the injected app API.
+ *
+ * Both type parameters are optional:
+ *   - `In`  types `job.variables` (the process variables the job carries).
+ *   - `Out` types the completion **variables map** the handler returns to the engine.
+ * Each defaults to an open `Record<string, unknown>`, so `AppJobHandler`,
+ * `AppJobHandler<In>`, and `AppJobHandler<In, Out>` are all valid.
+ *
+ * The bound is `extends object` (not `Record<string, unknown>`) so a plain `interface In {…}`
+ * / `interface Out {…}` can be supplied — interfaces have no implicit index signature and so
+ * don't satisfy a `Record` bound. The looser bound means `Out` is not *forced* to be a plain
+ * variables map at the type level; authors are expected to return a JSON-object of completion
+ * variables (not a `Date`, `Map`, array, etc.), which is what the engine sends on job
+ * completion. Both parameters are erased at runtime — they only shape authoring-time types.
+ */
+export type AppJobHandler<In extends object = Record<string, unknown>, Out extends object = Record<string, unknown>> = (
+  job: EngineJob<In>,
   app: AppApi,
-) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+) => Promise<Out | void> | Out | void;
 
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order: