[Submission] Temporal OneShot — Reliable One-Time Workflow Scheduling Made Simple

[harimanasa]

Project link

https://github.com/harimanasa/Temporal-OneShot

Language

TypeScript

Short description (max 256 chars)

A simple utility to reliably schedule one-time workflows in Temporal. Abstracts away interval/phase quirks, ensures exactly one execution, and provides validation + preview to prevent silent scheduling failures.

Long Description

🚀 Temporal OneShot — Simplifying One-Time Workflow Scheduling

Temporal schedules are powerful, but they are primarily designed for recurring workflows. Scheduling a workflow to run exactly once at a specific time requires non-intuitive constructs like intervals, phase offsets, and tightly scoped execution windows.

This often leads to:

Hidden complexity in schedule specs
Silent failures when intervals are missing
Confusing developer experience
Repeated boilerplate logic across services

💡 What This Project Solves

Temporal OneShot introduces a simple abstraction for fire-once workflows:

await scheduleOnce({
workflowType: "MyWorkflow",
runAt: new Date("2026-05-10T10:00:00.123Z"),
});

Instead of requiring developers to manually construct schedule specs, this utility:

Automatically generates a safe synthetic schedule
Aligns phase offset with millisecond precision
Ensures exactly one execution
Prevents duplicate or missed runs
⚙️ How It Works

Under the hood, Temporal OneShot creates a minimal schedule:

every = 1s → provides a cadence for Temporal’s scheduler
phase = runAt % 1000ms → aligns execution precisely
endAt = runAt + 1ms → restricts execution to a single tick

This guarantees that exactly one execution occurs, while keeping all complexity internal.

🔍 Validation & Preview

The tool also includes a validation layer:

npx temporal-oneshot validate --run-at "2026-05-10T10:00:00.123Z"

Output:

✅ Valid one-shot schedule
Next run: 2026-05-10T10:00:00.123Z
Execution count: exactly 1

This helps catch errors before deployment and improves developer confidence.

🎬 Demo
Input a timestamp (e.g., now + 10 seconds)
Create schedule via CLI or API
Observe:
Schedule creation
Exact execution time
Workflow runs once and completes

🎯 Why This Matters
Improves developer experience for Temporal users
Eliminates hidden scheduling pitfalls
Reduces production bugs caused by misconfigured schedules
Provides a reusable pattern for one-time execution

🔮 Future Enhancements
UI-based schedule playground
Timeline visualization of execution
Support for hybrid schedules (one-time + recurring)
Integration into Temporal SDK or extensions

🏁 Summary

Temporal workflows are powerful —
Temporal OneShot makes one-time scheduling simple, safe, and predictable.

Author(s)

Manasa Hari
Software Engineer, Adobe
GitHub: https://github.com/harimanasa
LinkedIn: https://www.linkedin.com/in/harimanasa/

[github-actions]

Hi, I'm ZiggyBot! 🤖 Here's my pre-evaluation of this submission:

---

Criterion	Assessment
Useful to Temporal users	⚠️ Unclear — The concept addresses a real pain point (one-time scheduling), but without code to review, it's impossible to verify the implementation actually works as described.
Benefits clearly explained	✅ Yes — The submission description clearly articulates the problem (complex schedule specs for one-time execution) and the solution (simple scheduleOnce abstraction with automatic phase alignment).
OSI Approved License	❌ No — No license was detected in the repository, which is required for community code sharing.
README with working instructions	❌ No — The repository has no README file, making it impossible for users to understand how to install or use the project.

Overall: Does not meet criteria ❌

Notes:

• The concept is genuinely interesting! Temporal's Schedule API is indeed optimized for recurring workflows, and a clean abstraction for one-time execution could save developers from common pitfalls.
• The technical approach described (using every=1s, precise phase offset, and endAt=runAt+1ms) is clever, though I'd love to see the actual implementation to verify it handles edge cases correctly.
• The repository appears to be essentially empty — no README, no license, and no visible source code. This feels like a submission for a project that's still in the planning/early development phase.
• Zero stars and no community validation yet, which is fine for new projects, but combined with missing files suggests this isn't ready for the Code Exchange.

Suggested questions for submitter:

• Could you add the source code, README with installation/usage instructions, and an OSI-approved license (MIT recommended) to the repository?
• Has this approach been tested against edge cases like clock skew between the Temporal Service and workers, or what happens if the runAt time has already passed?
• The description mentions a CLI (npx temporal-oneshot validate) — is this implemented and available in the repo?

Teaching moment:

The submission describes an interesting technique for one-time scheduling using Temporal's Schedule API: setting interval=1s with a precise phase offset and endAt=runAt+1ms to restrict execution to exactly one tick. This is a creative workaround for a common developer need! Unfortunately, without actual code in the repository, I can't point to a concrete implementation example. Once the code is available, this could be a great teaching example for how to compose Temporal's scheduling primitives for specialized use cases.

---

---

ZiggyBot is an AI pre-screener based on Temporal's community mascot Ziggy. Final decisions are made by the community team.

Reviewer: Check the box below to generate a Contentful-ready long description for this submission.

• Generate long description if needed

[github-actions]

Hi, I'm ZiggyBot! 🤖 Here's my pre-evaluation of this submission:

---

Criterion	Assessment
Useful to Temporal users	⚠️ Unclear — The concept of simplifying one-time scheduling addresses a real pain point, but without source code to verify the implementation approach, I can't confirm it works as described.
Benefits clearly explained	✅ Yes — The submission description thoroughly explains the problem (schedule spec complexity for one-time executions) and the proposed solution with clear examples.
OSI Approved License	❌ No — No license was detected in the repository, which is required for community contributions.
README with working instructions	❌ No — The repository has no README file, making it impossible for users to understand how to install or use the project.

Overall: Does not meet criteria ❌

Notes:

• The submission description is well-written and the problem being solved (simplifying one-time workflow scheduling) is genuinely useful — Temporal's Schedule API is indeed optimized for recurring executions.
• The repository appears to be essentially empty: 0 stars, no README, no detected license, and presumably no source code visible.
• The described approach using every=1s, phase=runAt % 1000ms, and endAt=runAt+1ms is creative, though I'd love to verify this actually produces exactly-once semantics in practice.
• This feels like a submission for a project that may still be in development or was submitted prematurely.

Suggested questions for submitter:

• Has the source code been pushed to the repository yet? The repo appears to be empty or incomplete.
• Could you add an OSI-approved license (MIT recommended) to the repository?
• Once code is available, would you be able to add a README with installation instructions and usage examples?
• Have you tested the endAt = runAt + 1ms approach to confirm Temporal's scheduler handles this edge case reliably across clock skew scenarios?

Teaching moment:

The submission describes an interesting technique for achieving one-time execution using Temporal Schedules: combining a minimal interval (every=1s), a precise phase offset (phase = runAt % 1000ms), and a tight end time (endAt = runAt + 1ms). This is a clever workaround for Schedule's recurring-first design! However, without source code to examine, I can't verify this pattern or provide a concrete code example. If the implementation is complete and published, this could be a valuable teaching example for the community about Schedule spec mechanics.

---

---

ZiggyBot is an AI pre-screener based on Temporal's community mascot Ziggy. Final decisions are made by the community team.

Reviewer: Check the box below to generate a Contentful-ready long description for this submission.

• Generate long description if needed

[github-actions]

Hi, I'm ZiggyBot! 🤖 Here's my pre-evaluation of this submission:

---

Criterion	Assessment
Useful to Temporal users	⚠️ Unclear — The concept of simplifying one-time scheduling is genuinely useful, but without a README or viewable source code, it's impossible to verify the implementation actually works as described.
Benefits clearly explained	⚠️ Unclear — The submission description is excellent and clearly articulates the problem and solution, but the repository itself has no README to explain benefits to users discovering the project.
OSI Approved License	❌ No — No license was detected in the repository, which means the code is technically "all rights reserved" by default.
README with working instructions	❌ No — The repository has no README file, making it impossible for users to understand how to install, configure, or use the project.

Overall: Does not meet criteria ❌

Notes:

• The submission description is wonderfully detailed and shows a solid understanding of Temporal's scheduling quirks! The problem being solved (one-time scheduling requiring non-intuitive interval/phase constructs) is real and the proposed solution is clever.
• However, the repository appears to be in a very early or incomplete state — no README, no detected license, and zero stars suggest this may have just been created or isn't ready for public showcase.
• The technique described (using every=1s, phase=runAt % 1000ms, endAt=runAt + 1ms) is creative, though I'd love to verify this actually produces exactly-once execution in practice.
• The CLI validation feature (npx temporal-oneshot validate) sounds helpful but can't be verified without documentation.

Suggested questions for submitter:

• Could you add a README with installation instructions, usage examples, and any prerequisites (Temporal server version, SDK version)?
• Would you be able to add an OSI-approved license (MIT is common and straightforward)?
• Is the source code complete and functional? It would help to see at least one working example.
• Have you tested the endAt = runAt + 1ms approach to confirm it reliably produces exactly one execution across different timing scenarios?

Teaching moment:

The submission describes an interesting approach to one-time scheduling: using a 1-second interval with a millisecond-precision phase offset and a tight endAt window. This is a creative workaround for Temporal's schedule system which is primarily designed for recurring executions. However, without access to the actual implementation code, I cannot verify this pattern or provide a concrete example. If the code were available, this would be a great teaching moment about how Temporal's schedule phase parameter aligns execution within an interval period — a feature many developers overlook!

---

---

ZiggyBot is an AI pre-screener based on Temporal's community mascot Ziggy. Final decisions are made by the community team.

Reviewer: Check the box below to generate a Contentful-ready long description for this submission.

• Generate long description if needed