@antelopejs/interface-redis-scheduler 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,248 @@
1
+ # Interface Redis Scheduler Documentation
2
+
3
+ ## Overview
4
+
5
+ Interface Redis Scheduler provides a distributed task scheduling system built on top of Redis. It stores tasks in a Redis sorted set with their due timestamps as scores, enabling precise scheduling and efficient retrieval of tasks that are ready to execute. The scheduler supports automatic retries for failed tasks and coordinates across multiple application instances using Redis pub/sub.
6
+
7
+ ## Getting Started
8
+
9
+ Install the package in your project:
10
+
11
+ ```bash
12
+ npm install @antelopejs/interface-redis-scheduler
13
+ ```
14
+
15
+ > **Note:** This package depends on `@antelopejs/interface-redis`. You must have it installed and configured for the scheduler to connect to Redis.
16
+
17
+ ## Core Concepts
18
+
19
+ The scheduler operates around three main ideas:
20
+
21
+ - **Handlers** process tasks of a specific type. Register them with `setHandler()` before scheduling any tasks.
22
+ - **Tasks** are stored in a Redis sorted set with their due time as the score. When a task is due, the scheduler calls the matching handler.
23
+ - **Listener** monitors the sorted set and executes tasks when they become due. Enable it with `enableListener()`.
24
+
25
+ ## `setHandler`
26
+
27
+ The `setHandler` function registers a handler for a specific task type. Each handler has a unique name and a callback function that receives the task data as a string.
28
+
29
+ ```typescript
30
+ import { setHandler } from "@antelopejs/interface-redis-scheduler";
31
+
32
+ setHandler("send-email", async (taskInfo) => {
33
+ const emailData = JSON.parse(taskInfo);
34
+ await sendEmail({
35
+ to: emailData.recipient,
36
+ subject: emailData.subject,
37
+ body: emailData.body,
38
+ });
39
+ });
40
+ ```
41
+
42
+ Handler names must not contain the `:` character, as the scheduler uses it internally as a delimiter.
43
+
44
+ ### Parameters
45
+
46
+ | Parameter | Type | Description |
47
+ | ------------- | ------------------------------------------- | ----------------------------------- |
48
+ | `handlerName` | `string` | Unique identifier for the task type |
49
+ | `handler` | `(taskInfo: string) => void \| Promise<void>` | Function that processes the task |
50
+
51
+ ## `enableListener`
52
+
53
+ The `enableListener` function starts the task execution loop. It creates a dedicated Redis subscriber connection to receive real-time notifications when new tasks are added, and sets up a timer to check for due tasks.
54
+
55
+ ```typescript
56
+ import { enableListener } from "@antelopejs/interface-redis-scheduler";
57
+
58
+ async function startApp() {
59
+ // Register all handlers first
60
+ // ...
61
+
62
+ // Then start the listener
63
+ await enableListener();
64
+ console.log("Scheduler is active");
65
+ }
66
+ ```
67
+
68
+ > **Important:** Register all task handlers before calling `enableListener()`. The listener begins processing tasks immediately.
69
+
70
+ ## `disableListener`
71
+
72
+ The `disableListener` function stops the scheduler from processing any further tasks. Call it during application shutdown.
73
+
74
+ ```typescript
75
+ import { disableListener } from "@antelopejs/interface-redis-scheduler";
76
+
77
+ async function stopApp() {
78
+ await disableListener();
79
+ console.log("Scheduler stopped");
80
+ }
81
+ ```
82
+
83
+ ## `addTask`
84
+
85
+ The `addTask` function schedules a task for execution at a specific time. The task is stored in a Redis sorted set with the due time as its score.
86
+
87
+ ```typescript
88
+ import { addTask } from "@antelopejs/interface-redis-scheduler";
89
+
90
+ async function scheduleReminder(userId: string) {
91
+ // Schedule for 3 days from now
92
+ const dueTime = Date.now() + 3 * 24 * 60 * 60 * 1000;
93
+
94
+ const taskInfo = JSON.stringify({
95
+ userId,
96
+ type: "password_reminder",
97
+ createdAt: new Date().toISOString(),
98
+ });
99
+
100
+ await addTask("send-email", dueTime, taskInfo);
101
+ }
102
+ ```
103
+
104
+ The function throws an error if the specified handler name has not been registered.
105
+
106
+ ### Parameters
107
+
108
+ | Parameter | Type | Description |
109
+ | ------------- | -------- | ------------------------------------------------------------ |
110
+ | `handlerName` | `string` | The registered handler name that processes this task |
111
+ | `dueTime` | `number` | Unix timestamp in milliseconds when the task should execute |
112
+ | `taskInfo` | `string` | Data passed to the handler (typically a JSON-encoded string) |
113
+
114
+ ## `removeTask`
115
+
116
+ The `removeTask` function cancels a previously scheduled task. The `taskInfo` string must match the one used when the task was added.
117
+
118
+ ```typescript
119
+ import { removeTask } from "@antelopejs/interface-redis-scheduler";
120
+
121
+ async function cancelReminder(userId: string) {
122
+ const taskInfo = JSON.stringify({
123
+ userId,
124
+ type: "password_reminder",
125
+ createdAt: "2025-04-05T12:00:00.000Z", // Must match exactly
126
+ });
127
+
128
+ await removeTask("send-email", taskInfo);
129
+ }
130
+ ```
131
+
132
+ The function throws an error if the specified handler name has not been registered.
133
+
134
+ > **Warning:** The `taskInfo` must be an exact string match of the original task. If the serialized JSON differs in key order or whitespace, the removal fails silently.
135
+
136
+ ### Parameters
137
+
138
+ | Parameter | Type | Description |
139
+ | ------------- | -------- | ------------------------------------------------- |
140
+ | `handlerName` | `string` | The handler name associated with the task |
141
+ | `taskInfo` | `string` | The exact task info string used when adding the task |
142
+
143
+ ## Retry Logic
144
+
145
+ The scheduler automatically retries failed tasks. When a handler throws an error, the scheduler reschedules the task with a retry counter.
146
+
147
+ - **Maximum retries:** 3 attempts
148
+ - **Retry delay:** 5 seconds between each attempt
149
+ - **Behavior on exhaustion:** After 3 failed retries, the task is discarded and the error is logged to the console
150
+
151
+ No additional code is required to enable retries. The mechanism is built into the task execution loop.
152
+
153
+ ```typescript
154
+ import { setHandler } from "@antelopejs/interface-redis-scheduler";
155
+
156
+ // If this handler throws, the scheduler retries up to 3 times
157
+ setHandler("process-payment", async (taskInfo) => {
158
+ const data = JSON.parse(taskInfo);
159
+ await processPayment(data);
160
+ // On failure: retry after 5s, then 5s, then 5s, then discard
161
+ });
162
+ ```
163
+
164
+ ## Redis Storage
165
+
166
+ The scheduler uses a single Redis sorted set with the key `SchedulerUtil.Tasks`. Each member in the sorted set follows the format `handlerName:taskInfo`, and its score is the due timestamp in milliseconds.
167
+
168
+ For retried tasks, the format becomes `RETRY-{count}:handlerName:taskInfo`, where `{count}` tracks the number of retry attempts.
169
+
170
+ The scheduler also uses a Redis pub/sub channel named `SchedulerUtil` to notify listener instances when new tasks are added, ensuring timers are updated across all nodes in a cluster.
171
+
172
+ ## `updateTimer`
173
+
174
+ The `updateTimer` function refreshes the internal timer that tracks the next due task. The scheduler calls this function automatically when tasks are added or completed. You do not need to call it in normal usage.
175
+
176
+ ```typescript
177
+ import { updateTimer } from "@antelopejs/interface-redis-scheduler";
178
+
179
+ // Force a timer refresh (advanced usage)
180
+ await updateTimer();
181
+ ```
182
+
183
+ ## `runTasks`
184
+
185
+ The `runTasks` function executes all tasks that are currently due. The scheduler calls this function automatically when the timer fires. It includes the retry logic for failed tasks. You do not need to call it in normal usage.
186
+
187
+ ```typescript
188
+ import { runTasks } from "@antelopejs/interface-redis-scheduler";
189
+
190
+ // Manually trigger task execution (advanced usage)
191
+ await runTasks();
192
+ ```
193
+
194
+ ## Complete Example
195
+
196
+ Here is a full integration example showing handler registration, listener startup, task scheduling, and shutdown.
197
+
198
+ ```typescript
199
+ import {
200
+ setHandler,
201
+ enableListener,
202
+ disableListener,
203
+ addTask,
204
+ removeTask,
205
+ } from "@antelopejs/interface-redis-scheduler";
206
+
207
+ // 1. Register task handlers
208
+ setHandler("send-email", async (taskInfo) => {
209
+ const data = JSON.parse(taskInfo);
210
+ await sendEmail(data.to, data.subject, data.body);
211
+ });
212
+
213
+ setHandler("cleanup-session", async (taskInfo) => {
214
+ const { sessionId } = JSON.parse(taskInfo);
215
+ await deleteSession(sessionId);
216
+ });
217
+
218
+ // 2. Start the listener
219
+ async function start() {
220
+ await enableListener();
221
+ }
222
+
223
+ // 3. Schedule tasks from your application logic
224
+ async function onUserSignup(userId: string, email: string) {
225
+ // Send a welcome email in 1 hour
226
+ const dueTime = Date.now() + 60 * 60 * 1000;
227
+ await addTask(
228
+ "send-email",
229
+ dueTime,
230
+ JSON.stringify({ to: email, subject: "Welcome!", body: "Thanks for signing up." }),
231
+ );
232
+ }
233
+
234
+ async function onUserLogout(sessionId: string) {
235
+ // Clean up session data in 24 hours
236
+ const dueTime = Date.now() + 24 * 60 * 60 * 1000;
237
+ await addTask(
238
+ "cleanup-session",
239
+ dueTime,
240
+ JSON.stringify({ sessionId }),
241
+ );
242
+ }
243
+
244
+ // 4. Stop the listener on shutdown
245
+ async function shutdown() {
246
+ await disableListener();
247
+ }
248
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-redis-scheduler",
3
- "version": "0.0.6",
3
+ "version": "0.0.7",
4
4
  "description": "AntelopeJS interface for Redis-based task scheduling",
5
5
  "keywords": [
6
6
  "antelopejs",
@@ -17,7 +17,9 @@
17
17
  "main": "dist/index.js",
18
18
  "types": "dist/index.d.ts",
19
19
  "files": [
20
- "dist"
20
+ "dist",
21
+ "docs",
22
+ "skills"
21
23
  ],
22
24
  "exports": {
23
25
  ".": {
@@ -59,6 +61,9 @@
59
61
  "access": "public"
60
62
  },
61
63
  "antelopeJs": {
62
- "test": "src/antelope.test.ts"
64
+ "test": "src/antelope.test.ts",
65
+ "skills": [
66
+ "./skills"
67
+ ]
63
68
  }
64
69
  }
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: redis-scheduler-interface
3
+ description: Distributed Redis-backed task scheduling for AntelopeJS - register named handlers, schedule tasks at a due timestamp in a Redis sorted set, and execute them with automatic retries coordinated across instances via pub/sub. Use when code imports '@antelopejs/interface-redis-scheduler', when a task involves scheduling delayed/deferred jobs, reminders, or background work in an AntelopeJS module, or when symbols like setHandler, addTask, removeTask, enableListener, disableListener, or the SchedulerUtil.Tasks Redis key appear.
4
+ category: antelopejs-interface
5
+ tags: [antelopejs, redis, scheduler, tasks, background-jobs]
6
+ ---
7
+
8
+ # Redis Scheduler Interface
9
+
10
+ Distributed task scheduler on top of Redis: tasks live in one sorted set
11
+ (`SchedulerUtil.Tasks`) scored by their due timestamp; listener instances
12
+ coordinate through the `SchedulerUtil` pub/sub channel. Mental model: this is a
13
+ consumer-side utility, not a proxied service. All exported functions run in
14
+ your own module; Redis access goes through `GetClient()` from
15
+ `@antelopejs/interface-redis` (`setHandler` itself is purely local, no Redis
16
+ call) - there is no provider to write with
17
+ `ImplementInterface`. A Redis interface implementation (e.g. the
18
+ `@antelopejs/redis` module) must be loaded in the app.
19
+
20
+ ## Imports
21
+
22
+ Only the package root is exported:
23
+
24
+ ```typescript
25
+ import {
26
+ setHandler,
27
+ enableListener,
28
+ disableListener,
29
+ addTask,
30
+ removeTask,
31
+ } from "@antelopejs/interface-redis-scheduler";
32
+ ```
33
+
34
+ (`updateTimer` and `runTasks` are also exported but belong to the internal
35
+ execution loop - only call them in tests or advanced scenarios.)
36
+
37
+ ## Consumption example
38
+
39
+ ```typescript
40
+ import {
41
+ setHandler,
42
+ enableListener,
43
+ disableListener,
44
+ addTask,
45
+ } from "@antelopejs/interface-redis-scheduler";
46
+
47
+ // 1. Register handlers first (name must not contain ':')
48
+ setHandler("overdue-notice", async (taskInfo) => {
49
+ const data = JSON.parse(taskInfo);
50
+ await notifyMember(data.memberId, data.bookTitle);
51
+ });
52
+
53
+ // 2. Start the execution loop (module start)
54
+ await enableListener();
55
+
56
+ // 3. Schedule a task: dueTime is a Unix timestamp in milliseconds
57
+ await addTask(
58
+ "overdue-notice",
59
+ Date.now() + 60 * 60 * 1000,
60
+ JSON.stringify({ memberId: "M-1042", bookTitle: "The Heron's Atlas" }),
61
+ );
62
+
63
+ // 4. On shutdown
64
+ await disableListener();
65
+ ```
66
+
67
+ ## Gotchas
68
+
69
+ - Handler names must not contain `:` - it delimits the sorted-set member
70
+ format `handlerName:taskInfo`. `setHandler` throws otherwise.
71
+ - `addTask` and `removeTask` throw for handler names not registered in the
72
+ current process. Always call `setHandler` before scheduling.
73
+ - Register all handlers before `enableListener()`; the listener starts
74
+ executing due tasks immediately.
75
+ - `taskInfo` is a plain string. Serialize/parse (typically JSON) yourself.
76
+ - `removeTask` needs the exact original `taskInfo` string; a JSON payload with
77
+ different key order or whitespace fails to match, silently removing nothing.
78
+ - Failed handlers are retried up to 3 times with a 5-second delay (the member
79
+ becomes `RETRY-{n}:handlerName:taskInfo`), then discarded; errors are logged
80
+ through interface-core `Logging.Error`.
81
+ - `enableListener` duplicates the shared Redis client into a dedicated
82
+ subscriber connection; `disableListener` quits that subscriber on shutdown.
83
+ - `disableListener` only quits the subscriber connection; it does not clear a
84
+ pending execution timer, so a task that comes due right after shutdown may
85
+ still run once. It also throws if `enableListener` was never called.
86
+ - Peer interfaces `@antelopejs/interface-core` and `@antelopejs/interface-redis`
87
+ must be installed alongside this package.
88
+
89
+ ## Deeper reference
90
+
91
+ See this package's `docs/1.introduction.md` (Overview, Getting Started, Core
92
+ Concepts, per-function sections, Retry Logic, Redis Storage, Complete Example)
93
+ and `dist/index.d.ts`. Do not duplicate them here.