@mnci/az-durable 0.1.1 → 0.1.3

package/dist/testing.cjs.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * Runs an orchestration against stubbed activities, with no Azure running.
+ *
+ * @remarks
+ * Drives the generator synchronously, feeding each yielded task the stubbed
+ * result for that activity's name. There is no host, no emulator and no
+ * storage — a three-step workflow with a short-circuit branch is testable in
+ * about fifteen lines.
+ *
+ * **How it intercepts.** The orchestration is driven with a fake
+ * `OrchestrationContext`, which works only because every scheduling call in
+ * this package goes through `context.df` rather than through the registered
+ * callable. The alternative — reading the name off `task.action.functionName` —
+ * is an undocumented SDK internal the package's non-goals forbid.
+ *
+ * **Limits, stated rather than discovered later.** Retry policies are not
+ * simulated: a stub returning an `Error` throws once, it does not exhaust
+ * attempts. `Task.any` resolves to the FIRST task in the list, since there is
+ * no real concurrency to race. Timers complete immediately.
+ *
+ * @param orchestration - The orchestration to run.
+ * @param input - The input, checked against its declared type.
+ * @param stub - The activity fakes, clock and instance id.
+ * @returns The result, the ordered calls, and the status transitions.
+ * @throws Error when an activity is called with no stub registered for it.
+ * @typeParam TInput - The orchestration's input type.
+ * @typeParam TOutput - The orchestration's output type.
+ */
+function runWorkflow(orchestration, input, stub) {
+  const calls = [];
+  const statuses = [];
+  let continuedAsNew;
+  const clock = stub.now ?? new Date(0);
+  const schedule = (name, scheduledInput) => {
+    calls.push({
+      name,
+      input: scheduledInput
+    });
+    return {
+      isCompleted: false,
+      isFaulted: false,
+      __name: name,
+      __input: scheduledInput
+    };
+  };
+  const context = {
+    df: {
+      instanceId: stub.instanceId ?? 'test-instance',
+      isReplaying: false,
+      currentUtcDateTime: clock,
+      callActivity: schedule,
+      callActivityWithRetry: (name, _retry, i) => schedule(name, i),
+      callSubOrchestrator: (name, i) => schedule(name, i),
+      callSubOrchestratorWithRetry: (name, _retry, i) => schedule(name, i),
+      waitForExternalEvent: name => schedule(name, undefined),
+      // Timers complete immediately: there is no real time to wait for, and a
+      // harness that blocked on one would be useless. `cancel` is real,
+      // because an orchestration that correctly cancels its losing timer must
+      // not crash in a test for doing the right thing.
+      createTimer: fireAt => {
+        const timer = schedule('__timer', fireAt.toISOString());
+        timer.isCanceled = false;
+        timer.cancel = () => {
+          timer.isCanceled = true;
+        };
+        return timer;
+      },
+      setCustomStatus: value => {
+        statuses.push(String(value));
+      },
+      continueAsNew: next => {
+        continuedAsNew = next;
+      },
+      Task: {
+        all: tasks => ({
+          isCompleted: false,
+          isFaulted: false,
+          __all: tasks
+        }),
+        // A marker, not a winner. `Task.any` resolves to the winning TASK, not
+        // to its value, so choosing here would hand the orchestration the
+        // wrong kind of thing — which is exactly the bug the reconstructed
+        // workflows found.
+        any: tasks => ({
+          isCompleted: false,
+          isFaulted: false,
+          __any: tasks
+        })
+      }
+    }
+  };
+  const generator = orchestration.handler(context, input);
+  let step = generator.next();
+  while (!step.done) {
+    const resumed = resolve(step.value, stub);
+    // INTO the generator, not out of the driver. Throwing here instead is the
+    // bug the reconstructed workflows found: every compensation branch was
+    // unreachable, while the docstring promised the opposite.
+    step = isThrowRequest(resumed) ? generator.throw(resumed.__throw) : generator.next(resumed);
+  }
+  return continuedAsNew === undefined ? {
+    result: step.value,
+    calls,
+    statuses
+  } : {
+    result: step.value,
+    calls,
+    statuses,
+    continuedAsNew
+  };
+}
+/**
+ * Produces the value the driver resumes a yielded task with.
+ *
+ * @remarks
+ * Separated so the `Task.all` fan-out case — where one yielded task stands for
+ * several — is handled in one place rather than inline in the drive loop.
+ *
+ * @param task - The task the orchestration yielded.
+ * @param stub - The stubs to resolve against.
+ * @returns The value to resume with, or a {@link ThrowRequest} for the driver to inject.
+ * @throws Error naming an activity with no stub registered.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function resolve(task, stub) {
+  const fanOut = task.__all;
+  if (fanOut !== undefined) {
+    return fanOut.map(t => resolve(t, stub));
+  }
+  const race = task.__any;
+  if (race !== undefined) {
+    return resolveRace(race, stub);
+  }
+  const {
+    __name: name,
+    __input: input
+  } = task;
+  if (name === '__timer') {
+    return undefined;
+  }
+  const activity = stub.activities[name];
+  if (activity === undefined) {
+    // Naming the activity matters: the alternative is `undefined` flowing into
+    // the orchestration and failing somewhere unrelated.
+    throw new Error(`No stub registered for '${name}'. Add it to stub.activities to run this workflow.`);
+  }
+  const result = activity(input);
+  if (result instanceof Error) {
+    // A returned Error becomes a THROWN error inside the orchestration, which
+    // is what makes failure branches testable at all. Handed back as a request
+    // so the DRIVER injects it; see {@link ThrowRequest}.
+    return {
+      __throw: result
+    };
+  }
+  return result;
+}
+/**
+ * Settles a `Task.any` race and returns the winning TASK.
+ *
+ * @remarks
+ * The distinction that matters: the SDK's `Task.any` resolves to the winning
+ * task object, not to its value, and callers read the value afterwards with
+ * `resultOf`. An earlier harness returned the resolved value instead, which
+ * made every orchestration using a race fail with "Task.any returned a task
+ * that was not one of the inputs" — correct code, rejected by the fake.
+ *
+ * The winner's `result` is populated and `isCompleted` set, so `resultOf` and
+ * an `isCompleted` check on the loser both behave as they do in production.
+ *
+ * @param candidates - The racing tasks.
+ * @param stub - The stubs to resolve the winner against.
+ * @returns The winning task, completed and carrying its result.
+ * @throws Error when `raceWinner` names a task that is not racing.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function resolveRace(candidates, stub) {
+  const names = candidates.map(c => c.__name);
+  const chosen = stub.raceWinner?.(names) ?? names[0];
+  const winner = candidates.find(c => c.__name === chosen);
+  if (winner === undefined) {
+    throw new Error(`raceWinner chose '${String(chosen)}', which is not racing. Candidates: ${names.join(', ')}.`);
+  }
+  const mutable = winner;
+  mutable.result = winner.__name === '__timer' ? undefined : resolve(winner, stub);
+  mutable.isCompleted = true;
+  return winner;
+}
+/**
+ * Whether a resolved value is a request to throw inside the orchestration.
+ *
+ * @param value - Whatever `resolve` produced.
+ * @returns `true` when the driver should call `generator.throw`.
+ * @throws Never - a type guard.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function isThrowRequest(value) {
+  return typeof value === 'object' && value !== null && '__throw' in value;
+}
+
+exports.runWorkflow = runWorkflow;
+//# sourceMappingURL=testing.cjs.js.map

package/package.json

@@ -1,32 +1,34 @@
 {
   "name": "@mnci/az-durable",
-  "version": "0.1.1",
-  "type": "module",
-  "main": "./dist/index.esm.js",
-  "module": "./dist/index.esm.js",
+  "version": "0.1.3",
+  "main": "./dist/index.cjs.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/src/index.d.ts",
-      "import": "./dist/index.esm.js",
-      "default": "./dist/index.esm.js"
+      "require": "./dist/index.cjs.js",
+      "import": "./dist/index.cjs.js",
+      "default": "./dist/index.cjs.js"
     },
     "./testing": {
       "types": "./dist/src/testing.d.ts",
-      "import": "./dist/testing.esm.js",
-      "default": "./dist/testing.esm.js"
+      "require": "./dist/testing.cjs.js",
+      "import": "./dist/testing.cjs.js",
+      "default": "./dist/testing.cjs.js"
     },
     "./eslint-plugin": {
       "types": "./dist/src/eslint-plugin.d.ts",
-      "import": "./dist/eslint-plugin.esm.js",
-      "default": "./dist/eslint-plugin.esm.js"
+      "require": "./dist/eslint-plugin.cjs.js",
+      "import": "./dist/eslint-plugin.cjs.js",
+      "default": "./dist/eslint-plugin.cjs.js"
     }
   },
   "files": [
     "dist",
     "!**/*.tsbuildinfo",
-    "!**/*.d.ts.map"
+    "!**/*.d.ts.map",
+    "!**/*.js.map"
   ],
   "publishConfig": {
     "access": "public"

package/dist/eslint-plugin.esm.js

@@ -1,363 +0,0 @@
-/**
- * Minimal ESLint rule shapes, declared locally.
- *
- * @remarks
- * Declared here rather than imported from `@types/eslint` or
- * `@typescript-eslint/utils` because this package ships **zero runtime
- * dependencies**, and a type-only dependency is still a dependency a consumer
- * must be able to resolve. These cover exactly what the three rules use.
- */ /**
- * Whether a call expression registers an orchestration.
- *
- * @remarks
- * Matches both `defineOrchestration(...)` and the raw
- * `df.app.orchestration(...)`, since an orchestration written either way has
- * the same determinism constraints.
- *
- * **Heuristic, by construction.** These rules match on call-site SHAPE, so an
- * orchestration body extracted into a helper function is not caught. That is a
- * documented limit rather than a defect: following the value would require type
- * information the rule deliberately does not depend on.
- *
- * @param node - A `CallExpression` node.
- * @returns `true` when the call registers an orchestration.
- * @throws Never - pure inspection.
- * @typeParam None - this function has no generic type parameters.
- */ function isOrchestrationRegistration(node) {
-    var callee = node.callee;
-    if (callee === undefined) {
-        return false;
-    }
-    if (callee.type === 'Identifier' && callee.name === 'defineOrchestration') {
-        return true;
-    }
-    // df.app.orchestration(...) — match on the trailing property, so any local
-    // alias for the namespace still matches.
-    if (callee.type === 'MemberExpression') {
-        var property = callee.property;
-        return (property === null || property === void 0 ? void 0 : property.type) === 'Identifier' && property.name === 'orchestration';
-    }
-    return false;
-}
-/**
- * The name a callee refers to, if it is a plain identifier or member access.
- *
- * @remarks
- * For a member expression this returns the TRAILING property, so `df.now()`
- * and `context.df.now()` both read as `now`. Callers that must distinguish a
- * bare call from a member call check `node.type` themselves - `require-yield-star`
- * does exactly that, because `yield c.df.callActivity(...)` is the correct raw
- * SDK call and must not be flagged.
- *
- * @param node - A callee node.
- * @returns The identifier or property name, or `undefined`.
- * @throws Never - pure inspection.
- * @typeParam None - this function has no generic type parameters.
- */ function calleeName(node) {
-    if (node === undefined) {
-        return undefined;
-    }
-    if (node.type === 'Identifier') {
-        return node.name;
-    }
-    if (node.type === 'MemberExpression') {
-        var property = node.property;
-        if ((property === null || property === void 0 ? void 0 : property.type) === 'Identifier') {
-            return property.name;
-        }
-    }
-    return undefined;
-}
-
-/** Global reads that differ on every replay, with the replacement to suggest. */ var FORBIDDEN_CALLS = {
-    'Date.now': 'now(context).getTime()',
-    'Math.random': 'context.df.newGuid(...) or an activity',
-    'crypto.randomUUID': 'context.df.newGuid(...)',
-    fetch: 'an activity — network calls must not run in an orchestrator',
-    axios: 'an activity — network calls must not run in an orchestrator'
-};
-/**
- * Flags non-deterministic operations inside an orchestration body.
- *
- * @remarks
- * The highest-value rule in the package. Each of these returns a DIFFERENT
- * value on every replay, and the failure is silent: the orchestration still
- * completes, it just produces output that disagrees with its own history.
- * Nothing in the runtime reports it.
- *
- * Every message names the replacement, because "this is non-deterministic" is
- * only half of what a reader needs.
- *
- * Heuristic by design — see {@link isOrchestrationRegistration}.
- */ var noNondeterministicOrchestrator = {
-    meta: {
-        type: 'problem',
-        docs: {
-            description: 'Disallow non-deterministic operations inside an orchestration.'
-        },
-        schema: [],
-        messages: {
-            forbidden: '{{what}} is non-deterministic on replay. Use {{fix}} instead.',
-            newDate: 'new Date() is non-deterministic on replay. Use now(context) instead.',
-            processEnv: 'process.env is read at replay time and may differ between deploys. ' + 'Read it in an activity, or pass it as orchestration input.'
-        }
-    },
-    create: function create(context) {
-        var depth = 0;
-        var enter = function enter(node) {
-            if (isOrchestrationRegistration(node)) {
-                depth += 1;
-            }
-        };
-        var exit = function exit(node) {
-            if (isOrchestrationRegistration(node)) {
-                depth -= 1;
-            }
-        };
-        return {
-            CallExpression: function CallExpression(node) {
-                var _calleeName;
-                enter(node);
-                if (depth === 0) {
-                    return;
-                }
-                var callee = node.callee;
-                var object = callee === null || callee === void 0 ? void 0 : callee.object;
-                var full = (object === null || object === void 0 ? void 0 : object.type) === 'Identifier' ? "".concat(String(object.name), ".").concat(String(calleeName(callee))) : (_calleeName = calleeName(callee)) !== null && _calleeName !== void 0 ? _calleeName : '';
-                var fix = FORBIDDEN_CALLS[full];
-                if (fix !== undefined) {
-                    context.report({
-                        node: node,
-                        messageId: 'forbidden',
-                        data: {
-                            what: full,
-                            fix: fix
-                        }
-                    });
-                }
-            },
-            'CallExpression:exit': exit,
-            NewExpression: function NewExpression(node) {
-                var _ref;
-                if (depth === 0) {
-                    return;
-                }
-                var callee = node.callee;
-                var args = node.arguments;
-                // `new Date(someInstant)` is fine and common — only the argument-less
-                // form reads the wall clock.
-                if ((callee === null || callee === void 0 ? void 0 : callee.type) === 'Identifier' && callee.name === 'Date' && ((_ref = args === null || args === void 0 ? void 0 : args.length) !== null && _ref !== void 0 ? _ref : 0) === 0) {
-                    context.report({
-                        node: node,
-                        messageId: 'newDate'
-                    });
-                }
-            },
-            MemberExpression: function MemberExpression(node) {
-                if (depth === 0) {
-                    return;
-                }
-                var object = node.object;
-                var property = node.property;
-                if ((object === null || object === void 0 ? void 0 : object.type) === 'Identifier' && object.name === 'process' && (property === null || property === void 0 ? void 0 : property.type) === 'Identifier' && property.name === 'env') {
-                    context.report({
-                        node: node,
-                        messageId: 'processEnv'
-                    });
-                }
-            }
-        };
-    }
-};
-
-/** SDK handler aliases that erase a handler's real signature. */ var ERASING_TYPES = new Set([
-    'ActivityHandler',
-    'OrchestrationHandler',
-    'FunctionHandler'
-]);
-/**
- * The annotation's type name, if it is a bare type reference.
- *
- * @param annotation - A node carrying a `typeAnnotation`, or `undefined`.
- * @returns The referenced type's name, or `undefined` when it is not a bare reference.
- * @throws Never - pure inspection.
- * @typeParam None - this function has no generic type parameters.
- */ function referencedName(annotation) {
-    var typeAnnotation = annotation === null || annotation === void 0 ? void 0 : annotation.typeAnnotation;
-    if ((typeAnnotation === null || typeAnnotation === void 0 ? void 0 : typeAnnotation.type) !== 'TSTypeReference') {
-        return undefined;
-    }
-    var typeName = typeAnnotation.typeName;
-    return (typeName === null || typeName === void 0 ? void 0 : typeName.type) === 'Identifier' ? typeName.name : undefined;
-}
-/**
- * Flags annotations that collapse a typed handler back to `any`.
- *
- * @remarks
- * **The rule that actually earns its keep**, because TypeScript cannot catch
- * this: the annotation is legal, so nothing errors — the types simply stop
- * meaning anything.
- *
- * `ActivityHandler` is an alias for `FunctionHandler`, which the SDK declares as
- * `(triggerInput: any, context: InvocationContext) => FunctionResult<any>`. So
- * annotating a handler with it discards the very signature `defineActivity`
- * exists to capture, and the activity silently becomes `any` in, `any` out. The
- * package then appears to work — every call compiles — while checking nothing.
- *
- * The second, nastier form is a middleware wrapper typed
- * `(h: ActivityHandler) => ActivityHandler`. That collapses EVERY handler it
- * wraps, so one `injectLogger` helper can quietly disable type safety across a
- * whole Function App. The fix is to make the wrapper generic:
- *
- * ```ts
- * const withLogging = <I, O>(h: (i: I, c: InvocationContext) => O) =>
- *   (i: I, c: InvocationContext): O => { c.log('...'); return h(i, c) }
- * ```
- */ var noUntypedActivityHandler = {
-    meta: {
-        type: 'problem',
-        docs: {
-            description: 'Disallow handler annotations that erase inferred types.'
-        },
-        schema: [],
-        messages: {
-            erased: "Annotating with '{{name}}' erases the handler's real signature — it is an alias for " + '(triggerInput: any, context) => any, so the activity becomes `any` in and `any` out. ' + 'Drop the annotation and let defineActivity infer it.',
-            erasedWrapper: "A wrapper typed '{{name}}' collapses every handler it wraps to `any`. " + 'Make it generic: <I, O>(h: (i: I, c: InvocationContext) => O) => (i: I, c: InvocationContext): O.'
-        }
-    },
-    create: function create(context) {
-        return {
-            // const handler: ActivityHandler = ...
-            Identifier: function Identifier(node) {
-                var _node_parent_type, _node_parent, _node_parent_params, _node_parent1;
-                var name = referencedName(node.typeAnnotation);
-                if (name === undefined || !ERASING_TYPES.has(name)) {
-                    return;
-                }
-                // A function PARAMETER annotated this way is the middleware form, which
-                // is worse: it erases every handler passed through it, not just one.
-                var isParameter = ((_node_parent = node.parent) === null || _node_parent === void 0 ? void 0 : (_node_parent_type = _node_parent.type) === null || _node_parent_type === void 0 ? void 0 : _node_parent_type.startsWith('TS')) === false && ((_node_parent1 = node.parent) === null || _node_parent1 === void 0 ? void 0 : (_node_parent_params = _node_parent1.params) === null || _node_parent_params === void 0 ? void 0 : _node_parent_params.includes(node)) === true;
-                context.report({
-                    node: node,
-                    messageId: isParameter ? 'erasedWrapper' : 'erased',
-                    data: {
-                        name: name
-                    }
-                });
-            }
-        };
-    }
-};
-
-/** The wrapper calls that must be delegated to, not yielded. */ var DELEGATED = new Set([
-    'callActivity',
-    'callSubOrchestration',
-    'all',
-    'any',
-    'waitForEvent',
-    'sleepFor',
-    'sleepUntil'
-]);
-/**
- * Flags `yield callActivity(...)` where `yield *` is meant.
- *
- * @remarks
- * **A convenience, not a safety net — and the build plan was wrong about this.**
- * The plan described bare `yield` as compiling silently to `any`, "the
- * difference between the package working and appearing to work". Measured
- * against the real typings, it is a COMPILE ERROR in both registration paths:
- * `TS2345` through `defineOrchestration` and `TS2322` through the SDK's own
- * `OrchestrationHandler`, because these helpers return a `Generator` and
- * yielding one where a `Task` is expected does not typecheck.
- *
- * The genuinely silent case is the RAW SDK — `yield context.df.callActivity(...)`
- * returns `any` and compiles — which is the baseline this package replaces.
- *
- * So this rule earns its place only by reporting a clearer message than
- * `TS2345` does. It is in `recommended` for that reason, not because anything
- * depends on it.
- */ var requireYieldStar = {
-    meta: {
-        type: 'suggestion',
-        docs: {
-            description: 'Require `yield *` when calling a delegating helper.'
-        },
-        schema: [],
-        messages: {
-            useYieldStar: "Use 'yield *' rather than 'yield' with {{name}}(). Delegation is what carries the " + 'result type; a bare yield does not typecheck, but the compiler error is obscure.'
-        }
-    },
-    create: function create(context) {
-        return {
-            YieldExpression: function YieldExpression(node) {
-                if (node.delegate === true) {
-                    return;
-                }
-                var argument = node.argument;
-                if ((argument === null || argument === void 0 ? void 0 : argument.type) !== 'CallExpression') {
-                    return;
-                }
-                // A BARE IDENTIFIER only. `c.df.callActivity(...)` is the raw SDK call,
-                // which is correct code and must not be flagged — matching the trailing
-                // property of a member expression would flag it, which a negative
-                // fixture caught.
-                var callee = argument.callee;
-                if ((callee === null || callee === void 0 ? void 0 : callee.type) !== 'Identifier') {
-                    return;
-                }
-                var name = callee.name;
-                if (DELEGATED.has(name)) {
-                    context.report({
-                        node: node,
-                        messageId: 'useYieldStar',
-                        data: {
-                            name: name
-                        }
-                    });
-                }
-            }
-        };
-    }
-};
-
-/**
- * Every rule this plugin ships, by name.
- *
- * @remarks
- * The keys are the names a config writes after the `az-durable/` prefix, so
- * renaming one is a breaking change for any consumer's config.
- */ var rules = {
-    'no-nondeterministic-orchestrator': noNondeterministicOrchestrator,
-    'no-untyped-activity-handler': noUntypedActivityHandler,
-    'require-yield-star': requireYieldStar
-};
-/**
- * The plugin object, for a flat config's `plugins` map.
- *
- * @remarks
- * Shipped from a separate entry point so lint rules are never a runtime import
- * of the wrapper itself.
- */ var plugin = {
-    rules: rules
-};
-/**
- * The recommended rule set.
- *
- * @remarks
- * Two errors and one warning, and the split is deliberate.
- * `no-nondeterministic-orchestrator` and `no-untyped-activity-handler` catch
- * failures nothing else does — silent replay corruption, and a type collapse
- * TypeScript accepts as legal. `require-yield-star` is a warning because the
- * compiler already rejects the code it flags; it only improves the message.
- */ var recommended = {
-    plugins: {
-        'az-durable': plugin
-    },
-    rules: {
-        'az-durable/no-nondeterministic-orchestrator': 'error',
-        'az-durable/no-untyped-activity-handler': 'error',
-        'az-durable/require-yield-star': 'warn'
-    }
-};
-
-export { noNondeterministicOrchestrator, noUntypedActivityHandler, plugin, recommended, requireYieldStar, rules };