@mnci/az-durable 0.1.0

package/README.md

@@ -0,0 +1,226 @@
+# @mnci/az-durable
+
+Compile-time type safety across the Azure Durable Functions
+orchestrator/activity boundary.
+
+The SDK types an activity call as `any` in and `any` out. Every input you pass
+and every result you read is unchecked, so a shape change on one side of the
+boundary surfaces at runtime, in an orchestration that may already have
+instances in flight. This package makes both ends typed, with no code
+generation, no fork, and nothing to keep in sync.
+
+```ts
+// Without: `article` is any. `article.titel` compiles.
+const article = yield context.df.callActivity('FetchArticle', { id })
+
+// With: `article` is FetchArticle's real return type. `article.titel` does not.
+const article = yield * callActivity(context, fetchArticle, { id })
+```
+
+## Install
+
+```bash
+npm install @mnci/az-durable
+```
+
+`durable-functions` (>=3 <4) and `@azure/functions` (>=4 <5) are **peer**
+dependencies — the ones your Function App already has. This package declares no
+dependencies of its own.
+
+## The mechanism, in one paragraph
+
+A generator has exactly one `TNext` shared by every `yield` in it, so
+`const x = yield callActivity(...)` can never be typed per call — whatever `x`
+is, it is the same type for every yield in the orchestration. `yield *` is
+different: it returns the *delegated* generator's `TReturn`, which **is** per
+call. That is the whole trick, and it is why every scheduling helper here is a
+generator you delegate to rather than a value you yield. Getting it wrong is a
+compile error, not a silent `any`.
+
+## Defining the boundary
+
+```ts
+import { defineActivity, defineOrchestration, callActivity } from '@mnci/az-durable'
+
+export const fetchArticle = defineActivity(
+  'FetchArticle',                                   // the registered name, verbatim
+  async (input: { id: string }) => await db.get(input.id)   // types inferred from here
+)
+
+export const publish = defineOrchestration(
+  'PublishArticle',
+  function * (context, input: { id: string }) {
+    const article = yield * callActivity(context, fetchArticle, { id: input.id })
+    return { title: article.title }
+  }
+)
+```
+
+Names are string literals you write, and the package will never generate one.
+**A name is baked into every orchestration's history**: renaming it breaks
+in-flight instances, which resume against the new code expecting the old name.
+Duplicate registrations throw at startup rather than silently shadowing.
+
+### Validating input at the boundary
+
+`context.df.getInput<T>()` is an unchecked cast — `T` is a claim the SDK never
+verifies. It matters more here than in ordinary code, because orchestration
+input comes back *out of the task hub*: an instance started by yesterday's
+deploy resumes against today's code, so a shape change between deploys arrives
+as a silently wrong object.
+
+```ts
+defineOrchestration('ResetSite', handler, { parse: parseResetRequest })
+```
+
+## Scheduling
+
+Every helper comes in two forms: a **generator** you `yield *` for the common
+sequential case, and a **task** you hold to run things concurrently.
+
+| Delegate with `yield *` | Hold as a task | Produces |
+| --- | --- | --- |
+| `callActivity` | `activityTask` | the activity's return type |
+| `callSubOrchestration` | `subOrchestrationTask` | the sub-orchestration's return type |
+| `waitForEvent` | `eventTask` | the event's payload type |
+| `sleepFor` / `sleepUntil` | `timerTask` / `timerTaskUntil` | `void` |
+
+### Fan-out
+
+`all` preserves a tuple positionally, and maps an array to an array:
+
+```ts
+const [html, slug] = yield * all(context, [
+  activityTask(context, renderHtml, draft),
+  activityTask(context, buildSlug, draft.title)
+])                                   // [string, string]
+
+const results = yield * all(
+  context,
+  items.map(i => activityTask(context, deleteItem, { id: i.id }))
+)                                    // { deleted: boolean, bytes: number }[]
+```
+
+### Racing
+
+`any` returns the **winning task**, matching the SDK. Read its value with
+`resultOf`, and identify the winner by identity:
+
+```ts
+const approval = eventTask(context, approved)
+const deadline = timerTask(context, ONE_DAY_MS)
+
+const winner = yield * any(context, [approval, deadline])
+if (winner === deadline) {
+  return { published: false, reason: 'approval timed out' }
+}
+if (!deadline.isCompleted()) {
+  deadline.cancel()          // REQUIRED — see below
+}
+const { approvedBy } = resultOf(approval)
+```
+
+**Cancel the losing timer.** An orchestration does not complete until every
+scheduled timer has fired or been cancelled, so a timeout timer left pending
+after its race is won keeps the instance alive until it expires. `timerTask`
+returns `cancel()` and `isCompleted()` for exactly this.
+
+### Retries
+
+`RetryOptions` is a class in the SDK, so an object literal cannot satisfy it.
+`retryPolicy` takes the plain object and builds a real instance:
+
+```ts
+yield * callActivity(context, store, input, retryPolicy({
+  firstRetryIntervalInMilliseconds: 1000,
+  maxNumberOfAttempts: 3,
+  backoffCoefficient: 2
+}))
+```
+
+### Restarting an eternal orchestration
+
+History grows with every call, so a sweep over an unbounded backlog must
+restart rather than keep going. `continueAsNew` arrives as a third handler
+argument, because it restarts *this* orchestration and so its input is checked
+against this orchestration's own type:
+
+```ts
+defineOrchestration('Cleanup', function * (context, input: Sweep, self) {
+  // ...
+  self.continueAsNew({ olderThanDays: input.olderThanDays })
+  return summary          // return immediately after; the SDK requires it
+})
+```
+
+## Testing
+
+`@mnci/az-durable/testing` drives an orchestration against stubbed activities
+with no Azure running — no host, no emulator, no storage.
+
+```ts
+import { runWorkflow } from '@mnci/az-durable/testing'
+
+const run = runWorkflow(publish, { id: 'a1' }, {
+  activities: { FetchArticle: () => ({ title: 'T' }) }
+})
+
+expect(run.result).toEqual({ title: 'T' })
+expect(run.calls.map(c => c.name)).toEqual(['FetchArticle'])   // order matters
+```
+
+- **`calls` is ordered**, because reordering two activity calls is a breaking
+  change to an orchestration. That makes it directly assertable.
+- **Returning an `Error` from a stub throws inside the orchestration**, so
+  `catch` branches and compensation paths are testable.
+- **`raceWinner` picks the winner of an `any`**, by scheduled name (a timer is
+  `__timer`). Without it the first candidate always wins and the other branch
+  is unreachable.
+- **`now` fixes the clock**; **`instanceId` sets the instance id.**
+- **`continuedAsNew`** reports a restart request. The harness records it and
+  lets the run finish rather than looping — an eternal orchestration restarts
+  forever by design. The next generation is a separate `runWorkflow` call.
+
+Stated rather than discovered later: **retry policies are not simulated** — a
+stub returning an `Error` throws once, it does not exhaust attempts. Timers
+complete immediately.
+
+## Lint rules
+
+```js
+// eslint.config.mjs
+import { recommended } from '@mnci/az-durable/eslint-plugin'
+export default [recommended]
+```
+
+| Rule | Default | What it catches |
+| --- | --- | --- |
+| `no-untyped-activity-handler` | error | `: ActivityHandler` and friends, which are aliases for `(any, context) => any` — legal TypeScript that silently erases the handler's real signature |
+| `no-nondeterministic-orchestrator` | error | `new Date()`, `Date.now`, `Math.random`, `crypto.randomUUID`, `process.env`, `fetch` inside an orchestration |
+| `require-yield-star` | warn | `yield callActivity(...)` where `yield *` is meant |
+
+`no-untyped-activity-handler` is the one that earns its keep: the annotation is
+legal, so nothing errors — the types simply stop meaning anything. Its nastier
+form is a middleware wrapper typed `(h: ActivityHandler) => ActivityHandler`,
+which collapses **every** handler it wraps, so one helper can disable type
+safety across a whole Function App.
+
+`require-yield-star` is a warning rather than an error because the compiler
+already rejects the code it flags (`TS2345` through `defineOrchestration`); the
+rule only says so more clearly.
+
+The determinism rule matches on call-site **shape** and does not follow values,
+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 need
+type information the rule deliberately does not depend on.
+
+## What this does not do
+
+- **No name generation.** See above; names are yours.
+- **Not engine-agnostic.** It is a typed layer over `durable-functions`, not an
+  abstraction that could target another engine.
+- **No `async`/`await` orchestrators.** Durable's replay model requires
+  generators.
+- **Not a fork or a patch.** Every call goes through the public SDK surface;
+  nothing here reads an undocumented internal.
+- **Entity functions are not covered.**

package/dist/eslint-plugin.d.ts

@@ -0,0 +1 @@
+export * from "./src/eslint-plugin";

package/dist/eslint-plugin.esm.js

@@ -0,0 +1,363 @@
+/**
+ * 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 };

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";