feat(logic): decouple compilation for template logic

[23harshitkumar]

Description

This PR addresses the architectural requirements for US-02 by strictly decoupling the TS Logic compilation step from the logic execution pipeline (init/trigger methods).

Previously, TemplateArchiveProcessor relied on implicit, iterative compilation hidden inside the trigger() and init() methods. This PR fully extracts that pipeline into a standalone, manually callable method, allowing upstream platforms (like template-playground) to explicitly validate compilation syntax prior to executing requests.

Key Changes

• Decoupled Compilation: Extracted the internal TypeScript-to-JavaScript compiler loop into a new publicly accessible compileLogic() method.
• Performance Caching: Introduced a compiledLogicCache to preserve compiled TwoSlashReturn outputs, eliminating expensive and redundant recompilations during successive trigger() calls on the same processor instance.
• Strict Guard Clauses: Removed all lazy compilation from init() and trigger(). Both methods now synchronously throw a descriptive Error if invoked before compileLogic() is executed.
• JSDoc Documentation: Updated the intellisense WARNING blocks for both init() and trigger() to document the new strictly-enforced prerequisite.
• Defensive Execution: Hardened the arguments passed to the JavaScriptEvaluator to explicitly resolve fallback values for currentTime and utcOffset, preventing potential undefined crashes in the V8 isolate.
• Unit Tests: Updated all existing test suites to successfully integrate the new await processor.compileLogic() requirement, and added new decoupled unit tests explicitly verifying the error rejection handling.

Context of PR

Guided by @sanketshevkar, this architectural refactor is required for the GSoC Template Playground project. Decoupling the logic compilation step allows the Playground UI to manually compile user-authored TypeScript and surface syntax errors before attempting to execute a mock request. Beyond the frontend benefits, this enforces a strict separation of concerns in the Engine (Build vs. Execute) and drastically improves backend performance by caching compiled logic instead of implicitly recompiling on every trigger.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR refactors TemplateArchiveProcessor to separate TypeScript compilation from execution and updates tests to require explicit compilation before calling init/trigger.

Changes:

• Added compileLogic() with an instance-level cache to compile TypeScript logic once and reuse it.
• Updated init() and trigger() to require prior compilation and to throw if called before compileLogic().
• Expanded and tightened tests to cover compilation behavior and the new precondition.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
src/TemplateArchiveProcessor.ts	Introduces compileLogic() + caching, and makes init/trigger depend on compiled output.
test/TemplateArchiveProcessor.test.ts	Updates tests to call compileLogic() explicitly and adds coverage for missing-compilation errors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[23harshitkumar]

@sanketshevkar LMK if this PR meets your expectations or if there are any changes to be made (especially the copilot suggestion regarding lazy compiling and backward compatibility)

We can continue this discussion here:
https://discord.com/channels/874841541787656263/1511081157314347141

[sanketshevkar]

Hardened the arguments passed to the JavaScriptEvaluator to explicitly resolve fallback values for currentTime and utcOffset, preventing potential undefined crashes in the V8 isolate.

What's this about, why is this needed? I'm not able to track the change associated with this.

[23harshitkumar]

Hardened the arguments passed to the JavaScriptEvaluator to explicitly resolve fallback values for currentTime and utcOffset, preventing potential undefined crashes in the V8 isolate.

What's this about, why is this needed? I'm not able to track the change associated with this.

My apologies! That bullet point was a mistake on my end. While I was rebasing this branch to fix a merge conflict with main, I saw the resolvedTime and resolvedOffset variables that had recently been added to upstream which helped with the case of missing time or timezone offset . I accidentally included that in my PR summary thinking it was part of my local changes. I'll remove that bullet point from the PR description now to avoid any confusion.

[23harshitkumar]

Update: Reverted to Lazy Compilation and Optional useCache param

I've updated the code so we don't accidentally break older apps like apap. I removed the strict error throwing and switched back to lazy compilation, meaning trigger and init will just automatically handle the compilation if it hasn't been done yet.

To make sure the playground still gets that performance boost, I added an optional useCache parameter to those methods. Older apps will ignore it and behave exactly as they did before, but clients that want to opt into the optimization can just pass true to use the cached logic.

[sanketshevkar]

Nit: Can you please update the argument name across the file and tests? This is the convention we follow to name arguments controlling a behaviour.