Skip to content

fix(ts): await async hooks and route their errors through hooksRaise - #554

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
Divit-aggarwal:fix/ts-await-async-hooks
Sep 27, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
Divit-aggarwal:fix/ts-await-async-hooks

Conversation

@Divit-aggarwal

Copy link
Copy Markdown
Contributor

What

laya-ts now waits for an async hook and applies hooksRaise to a rejection, as Python does since #277.
dispatchAsync runs each hook in order, awaiting any promise it returns, and Agent and Router use it for
the predict hooks and for onLoad and onEvict.

Why

dispatch called each hook and discarded what it returned, so an async hook ran detached:

  • the call resolved before the hook finished, so a rewrite of ctx.results or a ctx.skip(...) after its
    first await was lost
  • a rejection was an unhandled rejection even with hooksRaise: false, the mode meant to keep telemetry from
    failing a request. Node ends a process on an unhandled rejection by default.

A hook that awaits a metrics backend, which is the natural way to write one, hit both:

const agent = new Agent({ provider, hooksRaise: false });
await agent.systemOne(state, questions, {
  onPredictEnd: async (ctx) => { await metrics.send(ctx.usage); },   // rejects: backend down
});
// before: resolves first; the rejection is an Unhandled Rejection (Vitest reports it as an error)
// after:  waits for the hook; the failure is a console.warn and the call succeeds
//         (with hooksRaise true, the call rejects with the hook's error)

Design

  • dispatchAsync awaits each hook before the next and treats a rejection like a throw: raised, or warned when
    hooksRaise is false. A hook that returns nothing behaves as before.
  • Router.route is synchronous, so onRoute keeps the synchronous dispatch. That function no longer leaves a
    returned promise unhandled: a rejection is reported as a warning. The README says onRoute is not awaited.
  • dispatchAsync is not exported from the package index, and the hook types now allow a Promise<void> return.
  • onLoad and onEvict are awaited, so router.load resolves after an async lifecycle hook finishes. _agents
    is set before they fire, so a hook that calls router.load again gets the cached agent; a test covers it.

Behaviour change

Async hooks that used to run detached are now awaited, so a slow one lengthens the call it belongs to, and
load waits for slow onLoad and onEvict hooks. Synchronous hooks are unaffected.

Not part of this change: Python's per-hook timeout (hooks_timeout), which laya-ts has no equivalent of.

Tests

Six new tests in hooks.test.ts. Five fail on main and pass with this change (two of them also raise
Unhandled Rejection errors on main): an async end hook rewriting results after an await, an async start hook
skipping after an await, ordering across hooks, both hooksRaise modes for a rejecting hook, and Router hooks
together with a rejecting onRoute. The sixth passes on both: it guards the new await in load, checking that
an async onLoad hook can call router.load for the model being loaded without deadlocking.

How it was verified

cd laya-ts
npx tsc -p tsconfig.json --noEmit   # exit 0
npm test -- --run                   # 22 files, 376 tests passed
npm run test:package                # 1 package test passed
cd ..
ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120   # All checks passed
python -m compileall -q laya/ tests/                                   # exit 0

The hook, router, agent and language-temperature test files ran 5 times: 5 of 5 passed. The two Python
commands are the CI gates; no Python was changed.

Scope

  • TypeScript: hooks.ts, agent.ts, router.ts, the hook tests and one README paragraph
  • No new public export, no dependencies, no Python changes
  • No accuracy or performance claim is made

Checklist

  • Focused on one change
  • Rebased on the latest main
  • Tests pass locally
  • No public export added

Related: #277 (the Python change). #519 also edits _predictHooked and Router.predict, a few lines from these
call sites, so a small conflict is likely whichever merges second. #329 adds Router.route_batch and
predict_batch and would use dispatchAsync for their hooks.

Written with Claude Code; I've reviewed the change and re-run the verification myself.

dispatch called each hook and discarded what it returned. An async hook, the
natural way to write one that ships telemetry or reads a cache, therefore ran
detached: the call resolved before it finished, a rewrite of ctx.results or a
ctx.skip after its first await was lost, and a rejection was an unhandled
rejection even with hooksRaise=false, which ends a Node process by default.
Python awaits them (NandhaKishorM#277).

Add dispatchAsync, which waits for each hook in order and applies raiseErrors to
a rejection the way it does to a throw, and use it for the predict hooks in
Agent and Router and for onLoad and onEvict. Router.route is synchronous, so
onRoute keeps the synchronous dispatch; it now reports a rejecting hook as a
warning instead of leaving it unhandled. The hook types allow a promise return.

dispatchAsync is not exported from the package index, and a hook that returns
nothing behaves as before. Add tests for awaiting, ordering, rewriting and
skipping after an await, both hooksRaise modes, and a re-entrant router.load
from an async onLoad hook.

Per-hook timeouts (hooks_timeout) are not part of this change.
@NandhaKishorM
NandhaKishorM merged commit 173fccb into NandhaKishorM:main Sep 27, 2026
20 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Thanks @Divit-aggarwal, merged. Combined with #519: default hooks still run once per Router.predict, and now they are awaited. It ships in 0.3.21.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants