@empyria/restate 0.4.28 → 0.4.30

package/README.md

@@ -81,6 +81,9 @@ endpoint, then create jobs with either:
   starts with the application.** The job has the stable `id` you give it, so calling it on every start never adds a second
   job: the same request changes nothing, and a changed request (another schedule, target or payload) replaces the pending
   run under the same ID. Call it once the endpoint has registered, e.g. from `setupRestate`'s `registrationCallbackFn`.
+- `getCronJob({restateURL, id})`: the job's request and next run, or `null` when it does not exist;
+- `cancelCronJob({restateURL, id})`: cancels the pending run, clears the job and **reads it back**: it resolves only when
+  the job is really gone, and throws otherwise. Safe to repeat, and for a job that never existed.
 
 Cron expressions are `croner` patterns (five fields, or six with seconds for tests). The target handler is sent the
 `payload` as its input, or no input when there is none.

package/lib/Cron.js

@@ -156,6 +156,8 @@ const scheduleNextExecution = async (ctx, request) => {
 	const jobState = {
 		request,
 		next_execution_time: next.toString(),
+		// The same instant in ms since 1970, for callers that store or compare it.
+		next_execution_at: next.getTime(),
 		next_execution_id: await handle.invocationId,
 	}
 	ctx.set(JOB_STATE_NAME, jobState)
@@ -188,4 +190,34 @@ export async function ensureCronJob({ restateURL, id, ...request }) {
 	})
 }
 
+const checkJobId = (fn, id) => {
+	if (typeof id !== 'string' || !/^[A-Za-z0-9._:-]+$/.test(id)) {
+		throw new TypeError(`${fn} needs an id made of letters, digits, ".", "_", ":" and "-"`)
+	}
+}
+
+/**
+ * What a recurring job is doing now, from outside Restate: its request and next run, or `null` when no such job
+ * exists (never created, or cancelled).
+ * @param {{restateURL: string, id: string}} params
+ */
+export async function getCronJob({ restateURL, id }) {
+	checkJobId('getCronJob', id)
+	return (await sendMessage({ restateURL, name: 'CronJob', message: 'getInfo', key: id })) ?? null
+}
+
+/**
+ * Cancels a recurring job and checks that it is gone: the pending run is cancelled and the job's state cleared, then
+ * the job is read back. Resolves only when the job really does not exist any more, so a caller may act on it (for
+ * example move a card) without a second look. Safe to repeat, and safe for a job that never existed.
+ * @param {{restateURL: string, id: string}} params
+ * @returns {Promise<void>}
+ */
+export async function cancelCronJob({ restateURL, id }) {
+	checkJobId('cancelCronJob', id)
+	await sendMessage({ restateURL, name: 'CronJob', message: 'cancel', key: id })
+	const left = await getCronJob({ restateURL, id })
+	if (left) throw new Error(`Cron job '${id}' is still scheduled after it was cancelled`)
+}
+
 export { JOB_STATE_NAME }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.28",
+	"version": "0.4.30",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -26,22 +26,22 @@
 		"test:watch": "bun test --watch"
 	},
 	"dependencies": {
-		"@empyria/classification": "0.1.13",
-		"@empyria/common": "0.3.16",
+		"@empyria/classification": "0.1.14",
+		"@empyria/common": "0.3.17",
 		"@restatedev/pubsub": "0.3.2",
 		"@restatedev/pubsub-client": "0.3.2",
-		"@restatedev/restate-sdk": "1.17.4",
-		"@restatedev/restate-sdk-clients": "1.17.4",
-		"@restatedev/restate-sdk-core": "1.17.4",
-		"croner": "10.0.1"
+		"@restatedev/restate-sdk": "1.18.0",
+		"@restatedev/restate-sdk-clients": "1.18.0",
+		"@restatedev/restate-sdk-core": "1.18.0",
+		"croner": "11.0.0"
 	},
 	"devDependencies": {
-		"@ai-sdk/openai-compatible": "3.0.78",
+		"@ai-sdk/openai-compatible": "3.0.80",
 		"@ai-sdk/provider": "4.0.34",
 		"@restatedev/restate-server": "1.8.1",
-		"ai": "7.0.153",
-		"oxfmt": "0.74.0",
-		"oxlint": "1.89.0"
+		"ai": "7.0.156",
+		"oxfmt": "0.75.0",
+		"oxlint": "1.90.0"
 	},
 	"peerDependencies": {
 		"@ai-sdk/openai-compatible": "^3.0.60",

package/test/Cron.test.js

@@ -3,6 +3,8 @@ import {
 	cronJobInitiator,
 	cronJob,
 	ensureCronJob,
+	getCronJob,
+	cancelCronJob,
 	setJobStateName,
 	JOB_STATE_NAME,
 } from '../lib/Cron.js'
@@ -300,3 +302,46 @@ describe('retry policy', () => {
 		expect(cronJob.options?.retryPolicy ?? cronJob.retryPolicy).toBeDefined()
 	})
 })
+
+describe('getCronJob and cancelCronJob', () => {
+	const realFetch = globalThis.fetch
+	afterEach(() => {
+		globalThis.fetch = realFetch
+	})
+	const respond = (script) => {
+		const calls = []
+		globalThis.fetch = async (url) => {
+			calls.push(url)
+			const body = script.shift()
+			return new Response(body === undefined ? '' : JSON.stringify(body), { status: 200 })
+		}
+		return calls
+	}
+
+	test('getCronJob answers null when the job does not exist', async () => {
+		respond([undefined])
+		expect(await getCronJob({ restateURL: 'http://r', id: 'a:1' })).toBeNull()
+	})
+
+	test('cancelCronJob cancels, then reads the job back before it resolves', async () => {
+		const calls = respond([undefined, undefined])
+		await cancelCronJob({ restateURL: 'http://r', id: 'a:1' })
+		expect(calls).toEqual(['http://r/CronJob/a:1/cancel', 'http://r/CronJob/a:1/getInfo'])
+	})
+
+	test('cancelCronJob fails when the job is still there afterwards', async () => {
+		respond([undefined, { request: {} }])
+		expect(cancelCronJob({ restateURL: 'http://r', id: 'a:1' })).rejects.toThrow(
+			'still scheduled',
+		)
+	})
+
+	test('cancelCronJob fails when the cancel call fails', async () => {
+		globalThis.fetch = async () => new Response('', { status: 503, statusText: 'down' })
+		expect(cancelCronJob({ restateURL: 'http://r', id: 'a:1' })).rejects.toThrow('503')
+	})
+
+	test('cancelCronJob refuses an id that cannot be a job id', () => {
+		expect(cancelCronJob({ restateURL: 'http://r', id: 'a b' })).rejects.toThrow(TypeError)
+	})
+})