@mnci/az-durable 0.1.1 → 0.1.3

package/dist/index.cjs.js

@@ -0,0 +1,628 @@
+'use strict';
+
+var df = require('durable-functions');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var df__namespace = /*#__PURE__*/_interopNamespaceDefault(df);
+
+/**
+ * Duplicate-name detection for activities and orchestrations.
+ *
+ * @remarks
+ * Activity and orchestration names are **global to the Function App** and are
+ * baked into orchestration history in the task hub. Two features registering
+ * the same string is a silent misbinding: the second registration wins, and the
+ * first feature's calls quietly execute the wrong handler. Nothing surfaces
+ * until replay, by which point the history already refers to the wrong thing.
+ *
+ * Failing loudly at startup is strictly better, so registration throws.
+ */
+/** Every name registered so far, and where. Module-level, matching the SDK's own global scope. */
+const registered = new Map();
+/**
+ * Records a name, throwing if it was already taken.
+ *
+ * @remarks
+ * The error names **both** call sites when the stack makes them available. A
+ * bare "duplicate name" message sends the reader hunting through a Function App
+ * for the other registration, which is the slowest part of fixing this.
+ *
+ * @param kind - `activity` or `orchestration`, for the message.
+ * @param name - The name being registered.
+ * @returns Nothing.
+ * @throws Error when `name` has already been registered.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function claimName(kind, name) {
+  const previous = registered.get(name);
+  if (previous !== undefined) {
+    throw new Error(`Duplicate ${kind} name '${name}'. Names are global to the Function App and are ` + 'baked into orchestration history, so two registrations silently misbind.\n' + `  first registered at: ${previous}\n` + `  registered again at: ${callSite()}`);
+  }
+  registered.set(name, callSite());
+}
+/**
+ * The caller's source location, as best the stack can tell.
+ *
+ * @remarks
+ * Best-effort by design: stack formats differ across runtimes, and a bundled or
+ * minified app may yield nothing useful. A vague location beats throwing while
+ * building an error message, so an unreadable stack degrades to a placeholder
+ * rather than failing.
+ *
+ * @returns A `file:line:col` string, or `<unknown location>`.
+ * @throws Never - falls back to a placeholder.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function callSite() {
+  const stack = new Error('locate').stack;
+  if (stack === undefined) {
+    return '<unknown location>';
+  }
+  // [0] is the Error line, [1] is callSite, [2] is claimName, [3] is
+  // defineActivity/defineOrchestration, [4] is the consumer — the one we want.
+  const frame = stack.split('\n', 5)[4];
+  return frame === undefined ? '<unknown location>' : frame.trim().replace(/^at\s+/, '');
+}
+
+/**
+ * Registers an activity and remembers its input and output types.
+ *
+ * @remarks
+ * **Do not annotate `handler` as `ActivityHandler`.** That type is an alias for
+ * `FunctionHandler`, which the SDK declares as
+ * `(triggerInput: any, context: InvocationContext) => FunctionResult<any>` — so
+ * annotating it discards the very signature this function exists to capture and
+ * silently reduces the activity to `any` in and `any` out. The same applies to
+ * any middleware wrapper typed `(h: ActivityHandler) => ActivityHandler`; make
+ * such wrappers generic instead. Both traps are lintable — see the
+ * `no-untyped-activity-handler` rule.
+ *
+ * `TOutput` is wrapped in `Awaited` so an `async` handler contributes its
+ * resolved type rather than a `Promise`.
+ *
+ * @param name - The activity name, a literal. Never derived from a variable or
+ * file name: it is baked into orchestration history, so a rename breaks every
+ * in-flight instance.
+ * @param handler - The activity implementation.
+ * @returns The activity, carrying its input and output types.
+ * @throws Error when `name` is already registered.
+ * @typeParam TInput - The JSON-serialisable input.
+ * @typeParam TOutput - The handler's return type, awaited.
+ */
+function defineActivity(name, handler) {
+  claimName('activity', name);
+  const registered = df__namespace.app.activity(name, {
+    handler: handler
+  });
+  return {
+    name,
+    registered
+  };
+}
+/**
+ * Schedules an activity without yielding it, for fan-out.
+ *
+ * @remarks
+ * The single place in this package that schedules an activity. `callActivity`
+ * is implemented in terms of it, so there is exactly one line to audit against
+ * an SDK change.
+ *
+ * **Scheduled through `context`, not through `activity.registered`,** and the
+ * two are equivalent — verified in the SDK source rather than assumed:
+ *
+ * ```
+ * registered(input)             -> new AtomicTask(false, new CallActivityAction(name, input))
+ * context.df.callActivity(...)  -> new AtomicTask(false, new CallActivityAction(name, input))
+ * ```
+ *
+ * `RegisteredActivityTask` is an `AtomicTask` subclass that only ADDS
+ * `withRetry`; the retry paths are identical too, both producing
+ * `RetryableTask(AtomicTask(CallActivityWithRetryAction(...)))`. The action is
+ * what enters orchestration history, so replay is unaffected.
+ *
+ * Routing through `context` is what makes {@link runWorkflow} possible without
+ * reading `task.action.functionName` — an undocumented internal the package's
+ * non-goals forbid depending on. It also makes every helper here uniformly
+ * context-first.
+ *
+ * @param context - The orchestration context.
+ * @param activity - The activity to schedule.
+ * @param input - The input, checked against the activity's declared type.
+ * @param retry - Optional retry policy.
+ * @returns A scheduled task, for `all`/`any`.
+ * @throws Never - scheduling is synchronous and cannot fail here.
+ * @typeParam TInput - The activity's input type.
+ * @typeParam TOutput - The activity's output type.
+ */
+function activityTask(context, activity, input, retry) {
+  const task = retry === undefined ? context.df.callActivity(activity.name, input) : context.df.callActivityWithRetry(activity.name, retry, input);
+  return {
+    task
+  };
+}
+/**
+ * Calls an activity and returns its typed result.
+ *
+ * @remarks
+ * **Must be invoked with `yield*`, not `yield`.** The delegation is what carries
+ * the type: `yield*` returns this generator's `TReturn`, which is per-call
+ * generic, whereas a generator's `TNext` is shared by every `yield` and so can
+ * never be typed per call. A bare `yield` is a compile error rather than a
+ * silent `any` — `callActivity` returns a `Generator`, and yielding one where a
+ * `Task` is expected does not typecheck — but the error message is obscure, so
+ * prefer the lint rule's.
+ *
+ * Determinism is unaffected. The task yielded up to the Durable driver is the
+ * identical object a hand-written call would yield, so replay history and
+ * in-flight instances are untouched. This is a type-level change only.
+ *
+ * @param context - The orchestration context.
+ * @param activity - The activity to call.
+ * @param input - The input, checked against the activity's declared type.
+ * @param retry - Optional retry policy.
+ * @returns A generator to delegate to; its return value is the activity output.
+ * @throws Whatever the activity threw, once the driver resumes with a failure.
+ * @typeParam TInput - The activity's input type.
+ * @typeParam TOutput - The activity's output type.
+ */
+function* callActivity(context, activity, input, retry) {
+  const result = yield activityTask(context, activity, input, retry).task;
+  // The one cast in the package. The SDK resumes the generator with the
+  // activity's result typed `any`; `TOutput` is the claim `defineActivity`
+  // captured from the handler's real signature.
+  return result;
+}
+
+/**
+ * Registers an orchestration, handing the handler its deserialised input.
+ *
+ * @remarks
+ * The SDK's `OrchestrationHandler` takes **only** `context` — there is no input
+ * parameter — so this wrapper calls `getInput` itself and passes the result as a
+ * second argument. That is why consumers never write
+ * `context.df.getInput() as SomeType`.
+ *
+ * @param name - The orchestration name, a literal. Baked into history; never derive it.
+ * @param handler - The orchestration generator, receiving context and input.
+ * @param options - Optional input validation. See {@link DefineOrchestrationOptions}.
+ * @returns The orchestration, carrying its input and output types.
+ * @throws Error when `name` is already registered.
+ * @typeParam TInput - The JSON-serialisable input.
+ * @typeParam TOutput - The value the orchestration returns.
+ */
+function defineOrchestration(name, handler, options) {
+  claimName('orchestration', name);
+  const parse = options?.parse;
+  const bind = context => ({
+    name,
+    continueAsNew: next => {
+      context.df.continueAsNew(next);
+    }
+  });
+  const registered = df__namespace.app.orchestration(name, function* (context) {
+    const raw = context.df.getInput();
+    const input = parse === undefined ? raw : parse(raw);
+    return yield* handler(context, input, bind(context));
+  });
+  return {
+    name,
+    registered,
+    handler: (context, input) => handler(context, input, bind(context))
+  };
+}
+/**
+ * Calls a sub-orchestration and returns its typed result.
+ *
+ * @remarks
+ * **Must be invoked with `yield*`.** See `callActivity` for why delegation is
+ * what carries the type.
+ *
+ * @param orchestration - The sub-orchestration to call.
+ * @param input - The input, checked against its declared type.
+ * @param options - Optional instance id and retry policy.
+ * @returns A generator to delegate to; its return value is the sub-orchestration output.
+ * @throws Whatever the sub-orchestration threw, once the driver resumes with a failure.
+ * @typeParam TInput - The sub-orchestration's input type.
+ * @typeParam TOutput - The sub-orchestration's output type.
+ */
+function* callSubOrchestration(context, orchestration, input, options) {
+  const result = yield subOrchestrationTask(context, orchestration, input, options).task;
+  return result;
+}
+/**
+ * Schedules a sub-orchestration without yielding it.
+ *
+ * @remarks
+ * The task form of {@link callSubOrchestration}, so several sub-orchestrations
+ * can run concurrently through `all`. Fanning out over sub-orchestrations is
+ * the standard way to bound a large batch — each child gets its own history,
+ * so the parent's history does not grow with the batch size.
+ *
+ * @param context - The orchestration context.
+ * @param orchestration - The sub-orchestration to schedule.
+ * @param input - Its input, checked against its declared type.
+ * @param options - Optional fixed instance id and retry policy.
+ * @returns A task carrying the sub-orchestration's output type.
+ * @throws Never - scheduling only.
+ * @typeParam TInput - The sub-orchestration's input type.
+ * @typeParam TOutput - The sub-orchestration's output type.
+ */
+function subOrchestrationTask(context, orchestration, input, options) {
+  const retry = options?.retry;
+  const task = retry === undefined ? context.df.callSubOrchestrator(orchestration.name, input, options?.instanceId) : context.df.callSubOrchestratorWithRetry(orchestration.name, retry, input, options?.instanceId);
+  return {
+    task
+  };
+}
+
+/**
+ * Starts an orchestration with an input checked against its declared type.
+ *
+ * @remarks
+ * `DurableClient.startNew` takes the orchestration **name** and an options
+ * object carrying `input`, both untyped. This narrows the pair so a caller
+ * cannot start an orchestration with the wrong payload shape.
+ *
+ * @param client - The Durable client, from `df.getClient(context)`.
+ * @param orchestration - The orchestration to start.
+ * @param input - The input, checked against its declared type.
+ * @param options - Optional instance id.
+ * @returns The new instance id.
+ * @throws Propagates whatever the client throws.
+ * @typeParam TInput - The orchestration's input type.
+ * @typeParam TOutput - The orchestration's output type, unused at runtime.
+ */
+async function startOrchestration(client, orchestration, input, options) {
+  const instanceId = options?.instanceId;
+  return await client.startNew(orchestration.name, {
+    input,
+    ...(instanceId !== undefined && {
+      instanceId
+    })
+  });
+}
+
+/**
+ * Builds a real SDK `RetryOptions` from a plain object.
+ *
+ * @remarks
+ * Returns a genuine class instance rather than a structurally-similar literal,
+ * deliberately: handing `callActivityWithRetry` a plain object would depend on
+ * the SDK reading it structurally, which is undocumented and exactly the kind
+ * of internal this package refuses to rely on.
+ *
+ * Only the properties actually supplied are assigned, so the SDK's own
+ * defaults stand for the rest instead of being overwritten with `undefined`.
+ *
+ * @param policy - The retry settings.
+ * @returns An SDK `RetryOptions` instance.
+ * @throws Whatever the SDK constructor throws for an invalid interval.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function retryPolicy(policy) {
+  const options = new df.RetryOptions(policy.firstRetryIntervalInMilliseconds, policy.maxNumberOfAttempts);
+  if (policy.backoffCoefficient !== undefined) {
+    options.backoffCoefficient = policy.backoffCoefficient;
+  }
+  if (policy.maxRetryIntervalInMilliseconds !== undefined) {
+    options.maxRetryIntervalInMilliseconds = policy.maxRetryIntervalInMilliseconds;
+  }
+  if (policy.retryTimeoutInMilliseconds !== undefined) {
+    options.retryTimeoutInMilliseconds = policy.retryTimeoutInMilliseconds;
+  }
+  return options;
+}
+
+/**
+ * Waits for every task, preserving tuple positions.
+ *
+ * @remarks
+ * **Must be invoked with `yield *`.** Takes `context` because `Task.all` is an
+ * instance member of `context.df`, not a static — the build plan's
+ * context-free signature cannot reach it.
+ *
+ * @param context - The orchestration context.
+ * @param tasks - The scheduled tasks, as a tuple.
+ * @returns A generator whose return value is the outputs, in input order.
+ * @throws `AggregatedError` when any task failed, matching the SDK.
+ * @typeParam T - The tuple of tasks.
+ */
+function* all(context, tasks) {
+  const results = yield context.df.Task.all(tasks.map(t => t.task));
+  return results;
+}
+/**
+ * Waits for the first task to complete and returns **which one won**.
+ *
+ * @remarks
+ * Returns the winning task, not its result, because that is what the SDK does:
+ * `Task.any` is documented as returning "the first Task from tasks to
+ * complete", and the SDK's own example compares it by identity
+ * (`if (winner === otherTask)`). The build plan's signature returned the
+ * output type instead, which would hand back a `Task` at runtime while the
+ * compiler believed it was the output — the exact class of silent mistyping
+ * this package exists to prevent.
+ *
+ * The winner is mapped back to the `TypedTask` the caller passed, so `===`
+ * against the original works. Read its value with {@link resultOf}.
+ *
+ * **Must be invoked with `yield *`.**
+ *
+ * @param context - The orchestration context.
+ * @param tasks - The scheduled tasks.
+ * @returns A generator whose return value is the winning task.
+ * @throws Error when the SDK returns a task that was not one of the inputs.
+ * @typeParam T - The tuple of tasks.
+ */
+function* any(context, tasks) {
+  const won = yield context.df.Task.any(tasks.map(t => t.task));
+  const winner = tasks.find(t => t.task === won);
+  if (winner === undefined) {
+    // Not defensive padding: if this ever fires, the SDK returned something
+    // other than one of the tasks handed to it, and silently returning the
+    // wrong element would misroute the branch the caller takes next.
+    throw new Error('Task.any returned a task that was not one of the inputs.');
+  }
+  return winner;
+}
+/**
+ * Reads a completed task's result, typed.
+ *
+ * @remarks
+ * `Task.result` is declared `unknown` by the SDK. This applies the output type
+ * the `TypedTask` was carrying all along. Only meaningful after the task has
+ * completed — typically on the winner from {@link any}.
+ *
+ * @param task - A completed task.
+ * @returns Its result, typed as the task's output.
+ * @throws Never - reads a property.
+ * @typeParam TOutput - The task's output type.
+ */
+function resultOf(task) {
+  return task.task.result;
+}
+
+/**
+ * Declares an external event and its payload type.
+ *
+ * @remarks
+ * Deliberately does not register anything — external events have no
+ * registration step in Durable Functions. This exists only to pair a name with
+ * a payload type so the waiter and the raiser cannot disagree.
+ *
+ * @param name - The event name, a literal.
+ * @returns The event reference.
+ * @throws Never - constructs an object.
+ * @typeParam TPayload - The payload type.
+ */
+function defineEvent(name) {
+  return {
+    name
+  };
+}
+/**
+ * Waits for an external event and returns its typed payload.
+ *
+ * @remarks
+ * **Must be invoked with `yield *`.**
+ *
+ * @param context - The orchestration context.
+ * @param event - The event to wait for.
+ * @returns A generator whose return value is the event payload.
+ * @throws Never - resolves when the event arrives.
+ * @typeParam TPayload - The payload type.
+ */
+function* waitForEvent(context, event) {
+  const payload = yield eventTask(context, event).task;
+  return payload;
+}
+/**
+ * Schedules a wait for an external event, without yielding it.
+ *
+ * @remarks
+ * The task form of {@link waitForEvent}, and the reason it exists is a gap the
+ * reconstructed workflows found: `any` and `all` take `TypedTask`s, so with
+ * only the generator form the single most common Durable Functions pattern —
+ * **wait for human approval, or time out** — could not be expressed at all.
+ *
+ * Pair it with {@link timerTask} and hand both to `any`.
+ *
+ * @param context - The orchestration context.
+ * @param event - The event to wait for.
+ * @returns A task carrying the event's payload type.
+ * @throws Never - scheduling only.
+ * @typeParam TPayload - The payload type.
+ */
+function eventTask(context, event) {
+  return {
+    task: context.df.waitForExternalEvent(event.name)
+  };
+}
+/**
+ * Raises an external event to a waiting instance, with a checked payload.
+ *
+ * @remarks
+ * The client half of {@link waitForEvent}. Pairing both sides through the same
+ * `EventRef` is what stops the raiser and the waiter disagreeing about the
+ * payload shape — the SDK types `eventData` as `unknown`, so nothing else would.
+ *
+ * @param client - The Durable client.
+ * @param instanceId - The instance to signal.
+ * @param event - The event being raised.
+ * @param payload - The payload, checked against the event's declared type.
+ * @returns A promise resolving when the event is enqueued.
+ * @throws Propagates whatever the client throws.
+ * @typeParam TPayload - The payload type.
+ */
+async function raiseEvent(client, instanceId, event, payload) {
+  await client.raiseEvent(instanceId, event.name, payload);
+}
+
+/**
+ * The current time, safely for replay.
+ *
+ * @remarks
+ * `new Date()` and `Date.now()` return a different value on every replay, which
+ * silently corrupts orchestration output rather than failing. `currentUtcDateTime`
+ * is derived from orchestration history and returns the same value at the same
+ * point every time. This is the replacement the lint rule suggests.
+ *
+ * @param context - The orchestration context.
+ * @returns The replay-safe current time.
+ * @throws Never - reads a property.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function now(context) {
+  return context.df.currentUtcDateTime;
+}
+/**
+ * Sleeps until an absolute time.
+ *
+ * @remarks
+ * **Must be invoked with `yield *`.**
+ *
+ * @param context - The orchestration context.
+ * @param when - The absolute time to wake at.
+ * @returns A generator that completes when the timer fires.
+ * @throws Never - the timer either fires or the instance ends.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function* sleepUntil(context, when) {
+  yield context.df.createTimer(when);
+}
+/**
+ * Sleeps for a duration.
+ *
+ * @remarks
+ * The deadline is computed from {@link now}, **never** `Date.now()`. Using wall
+ * clock here would make the deadline move on every replay, so a timer could fire
+ * early, late, or repeatedly. This is the single most common determinism bug in
+ * hand-written orchestrations.
+ *
+ * **Must be invoked with `yield *`.**
+ *
+ * @param context - The orchestration context.
+ * @param ms - How long to sleep, in milliseconds.
+ * @returns A generator that completes when the timer fires.
+ * @throws Never - the timer either fires or the instance ends.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function* sleepFor(context, ms) {
+  yield* sleepUntil(context, new Date(now(context).getTime() + ms));
+}
+/**
+ * Schedules a durable timer for an absolute instant, without yielding it.
+ *
+ * @remarks
+ * The task form of {@link sleepUntil}, so a timer can race an event or an
+ * activity through `any`. See {@link TypedTimerTask} for why the returned
+ * value carries `cancel` — **a pending timer keeps the instance alive**, so the
+ * loser of a race must be cancelled.
+ *
+ * @param context - The orchestration context.
+ * @param when - The instant to fire at.
+ * @returns A cancellable timer task.
+ * @throws Never - scheduling only.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function timerTaskUntil(context, when) {
+  const task = context.df.createTimer(when);
+  return {
+    task,
+    cancel: () => {
+      task.cancel();
+    },
+    isCompleted: () => task.isCompleted
+  };
+}
+/**
+ * Schedules a durable timer a fixed duration ahead, without yielding it.
+ *
+ * @remarks
+ * Computes the deadline from `context.df.currentUtcDateTime`, never
+ * `Date.now()` — the same replay-safety reason {@link sleepFor} does.
+ *
+ * @param context - The orchestration context.
+ * @param ms - How far ahead to fire, in milliseconds.
+ * @returns A cancellable timer task.
+ * @throws Never - scheduling only.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function timerTask(context, ms) {
+  return timerTaskUntil(context, new Date(now(context).getTime() + ms));
+}
+
+/**
+ * Declares the custom statuses an orchestration can report.
+ *
+ * @remarks
+ * `const` on the type parameter preserves the literal types, so `setStatus`
+ * can check the key against the actual set rather than against `string`. The
+ * object is returned unchanged — this is a typing device, not a transform.
+ *
+ * @param statuses - The status map.
+ * @returns The same object, with its literal types preserved.
+ * @throws Never - returns its argument.
+ * @typeParam T - The status map's literal type.
+ */
+function defineStatuses(statuses) {
+  return statuses;
+}
+/**
+ * Sets the orchestration's custom status from a declared set.
+ *
+ * @remarks
+ * `setCustomStatus` accepts `unknown`, so a typo in a status string is invisible
+ * until someone reads the instance's status and finds a value nothing produces.
+ * Constraining `key` to the declared map is the whole point.
+ *
+ * @param context - The orchestration context.
+ * @param statuses - The declared status map.
+ * @param key - Which status to set; checked against the map.
+ * @returns Nothing.
+ * @throws Never - delegates to the SDK.
+ * @typeParam T - The status map's literal type.
+ */
+function setStatus(context, statuses, key) {
+  context.df.setCustomStatus(statuses[key]);
+}
+
+exports.activityTask = activityTask;
+exports.all = all;
+exports.any = any;
+exports.callActivity = callActivity;
+exports.callSubOrchestration = callSubOrchestration;
+exports.defineActivity = defineActivity;
+exports.defineEvent = defineEvent;
+exports.defineOrchestration = defineOrchestration;
+exports.defineStatuses = defineStatuses;
+exports.eventTask = eventTask;
+exports.now = now;
+exports.raiseEvent = raiseEvent;
+exports.resultOf = resultOf;
+exports.retryPolicy = retryPolicy;
+exports.setStatus = setStatus;
+exports.sleepFor = sleepFor;
+exports.sleepUntil = sleepUntil;
+exports.startOrchestration = startOrchestration;
+exports.subOrchestrationTask = subOrchestrationTask;
+exports.timerTask = timerTask;
+exports.timerTaskUntil = timerTaskUntil;
+exports.waitForEvent = waitForEvent;
+//# sourceMappingURL=index.cjs.js.map