Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit cb060d9

Browse files
climba03003climba03003
committedOct 14, 2024
👨‍💻 Add types declaration file
1 parent ad2d4d3 commit cb060d9

File tree

5 files changed

+531
-0
lines changed

5 files changed

+531
-0
lines changed
 

‎adapters/blank-example.d.ts

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
export interface BlankAdapterOption {
2+
requiredOption: unknown;
3+
prefix?: string;
4+
resetOnInit?: boolean;
5+
}
6+
7+
export class BlankAdapter {
8+
/**
9+
* Create a BlankAdapter instance
10+
* @param {object} opts - configuration object
11+
* @param {object} opts.requiredOption - Required option description
12+
* @param {string} [opts.prefix] - prefix for scope isolation; use when creating multiple JoSK instances within the single application
13+
* @param {boolean} [opts.resetOnInit] - Make sure all old tasks is completed before setting a new one, see readme for more details
14+
*/
15+
constructor(opts?: BlankAdapterOption);
16+
name: string;
17+
prefix: string;
18+
resetOnInit: boolean;
19+
uniqueName: string;
20+
lockKey: string;
21+
requiredOption: unknown;
22+
/**
23+
* @async
24+
* @memberOf BlankAdapter
25+
* @name ping
26+
* @description Check connection to Storage
27+
* @returns {Promise<void>}
28+
*/
29+
ping(): Promise<void>;
30+
/**
31+
* @async
32+
* @memberOf BlankAdapter
33+
* Function called to acquire read/write lock on Storage adapter
34+
* @name acquireLock
35+
* @returns {Promise<boolean>}
36+
*/
37+
acquireLock(): Promise<boolean>;
38+
/**
39+
* @async
40+
* @memberOf BlankAdapter
41+
* Function called to release write/read lock from Storage adapter
42+
* @name releaseLock
43+
* @returns {Promise<void 0>}
44+
*/
45+
releaseLock(): Promise<void>;
46+
/**
47+
* @async
48+
* @memberOf BlankAdapter
49+
* Function called to remove task from the storage
50+
* @name remove
51+
* @param {string} uid - Unique ID of the task
52+
* @returns {Promise<boolean>}
53+
*/
54+
remove(uid: string): Promise<boolean>;
55+
/**
56+
* @async
57+
* @memberOf BlankAdapter
58+
* Function called to add task to the storage
59+
* @name add
60+
* @param {string} uid - Unique ID of the task
61+
* @param {boolean} isInterval - true/false defining loop or one-time task
62+
* @param {number} delay - Delay in milliseconds
63+
* @returns {Promise<void 0>}
64+
*/
65+
add(uid: string, isInterval: boolean, delay: number): Promise<void>;
66+
/**
67+
* @async
68+
* @memberOf BlankAdapter
69+
* Function called after executing tasks
70+
* Used by "Interval" tasks to set the next execution
71+
* @name update
72+
* @param {object} task - Full object of the task from storage
73+
* @param {Date} nextExecuteAt - Date defining time of the next execution for "Interval" tasks
74+
* @returns {Promise<boolean>} - `true` if updated, `false` id doesn't exist
75+
*/
76+
update(task: unknown, nextExecuteAt: Date): Promise<boolean>;
77+
/**
78+
* @async
79+
* @memberOf BlankAdapter
80+
* Find and run tasks one by one
81+
* @name iterate
82+
* @param {Date} nextExecuteAt - Date defining time of the next execution for "zombie" tasks
83+
* @param {function} cb - callback that must get called after looping over tasks
84+
* @returns {void 0}
85+
*/
86+
iterate(nextExecuteAt: Date): void;
87+
}

‎adapters/mongo.d.ts

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import { Db } from 'mongodb';
2+
3+
export interface MongoAdapterOption {
4+
db: Db;
5+
lockCollectionName?: string;
6+
prefix?: string;
7+
resetOnInit?: boolean;
8+
}
9+
10+
/** Class representing MongoDB adapter for JoSk */
11+
export class MongoAdapter {
12+
/**
13+
* Create a MongoAdapter instance
14+
* @param {JoSk} joskInstance - JoSk instance
15+
* @param {object} opts - configuration object
16+
* @param {Db} opts.db - Required, Mongo's `Db` instance, like one returned from `MongoClient#db()` method
17+
* @param {string} [opts.lockCollectionName] - custom "lock" collection name
18+
* @param {string} [opts.prefix] - prefix for scope isolation; use when creating multiple JoSK instances within the single application
19+
* @param {boolean} [opts.resetOnInit] - Make sure all old tasks is completed before setting a new one, see readme for more details
20+
*/
21+
constructor(opts?: MongoAdapterOption);
22+
name: string;
23+
prefix: string;
24+
lockCollectionName: string;
25+
resetOnInit: boolean;
26+
db: Db;
27+
uniqueName: string;
28+
collection: any;
29+
lockCollection: any;
30+
/**
31+
* @async
32+
* @memberOf MongoAdapter
33+
* @name ping
34+
* @description Check connection to MongoDB
35+
* @returns {Promise<object>}
36+
*/
37+
ping(): Promise<unknown>;
38+
acquireLock(): Promise<boolean>;
39+
releaseLock(): Promise<void>;
40+
remove(uid: string): Promise<boolean>;
41+
add(uid: string, isInterval: boolean, delay: number): Promise<boolean>;
42+
update(task: unknown, nextExecuteAt: Date): Promise<boolean>;
43+
iterate(nextExecuteAt: Date): Promise<void>;
44+
}

‎adapters/redis.d.ts

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import { RedisClientType as RedisClient } from 'redis';
2+
3+
export interface RedisAdapterOption {
4+
client: RedisClient;
5+
lockCollectionName?: string;
6+
prefix?: string;
7+
resetOnInit?: boolean;
8+
}
9+
10+
/** Class representing Redis adapter for JoSk */
11+
export class RedisAdapter {
12+
/**
13+
* Create a RedisAdapter instance
14+
* @param {object} opts - configuration object
15+
* @param {RedisClient} opts.client - Required, Redis'es `RedisClient` instance, like one returned from `await redis.createClient().connect()` method
16+
* @param {string} [opts.lockCollectionName] - custom "lock" collection name
17+
* @param {string} [opts.prefix] - prefix for scope isolation; use when creating multiple JoSK instances within the single application
18+
* @param {boolean} [opts.resetOnInit] - Make sure all old tasks is completed before setting a new one, see readme for more details
19+
*/
20+
constructor(opts?: RedisAdapterOption);
21+
name: string;
22+
prefix: string;
23+
uniqueName: string;
24+
lockKey: string;
25+
resetOnInit: boolean;
26+
client: RedisClient;
27+
/**
28+
* @async
29+
* @memberOf RedisAdapter
30+
* @name ping
31+
* @description Check connection to Redis
32+
* @returns {Promise<object>}
33+
*/
34+
ping(): Promise<unknown>;
35+
acquireLock(): Promise<boolean>;
36+
releaseLock(): Promise<void>;
37+
remove(uid: string): Promise<boolean>;
38+
add(uid: string, isInterval: boolean, delay: number): Promise<boolean>;
39+
update(task: unknown, nextExecuteAt: Date): Promise<boolean>;
40+
iterate(nextExecuteAt: Date): Promise<void>;
41+
__getTaskKey(uid: string): string;
42+
}

‎index.d.cts

+220
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
import { Db } from 'mongodb';
2+
import { RedisClientType as RedisClient } from 'redis';
3+
interface ErrorDetails {
4+
description: string
5+
error: Error
6+
uid: null | string
7+
task?: unknown
8+
}
9+
10+
interface ExecutedDetails {
11+
uid: string
12+
date: Date
13+
delay: number
14+
timestamp: number
15+
}
16+
17+
type OnErrorFunc = (title: string, details: ErrorDetails) => void
18+
type OnExecutedFunc = (uid: string, details: ExecutedDetails) => void
19+
type AsyncTaskFunc = () => Promise<void>
20+
type SyncTaskFunc = () => void
21+
type SyncNextTaskFunc = (ready: (next?: Date) => void) => void
22+
23+
export interface JoSkOption {
24+
debug?: boolean;
25+
onError?: OnErrorFunc;
26+
autoClear?: boolean;
27+
zombieTime?: number;
28+
onExecuted?: OnExecutedFunc;
29+
minRevolvingDelay?: number;
30+
maxRevolvingDelay?: number;
31+
}
32+
33+
/** Class representing a JoSk task runner (cron). */
34+
export class JoSk {
35+
/**
36+
* Create a JoSk instance
37+
* @param {object} opts - configuration object
38+
* @param {boolean} [opts.debug] - Enable debug logging
39+
* @param {function} [opts.onError] - Informational hook, called instead of throwing exceptions, see readme for more details
40+
* @param {boolean} [opts.autoClear] - Remove obsolete tasks (any tasks which are not found in the instance memory during runtime, but exists in the database)
41+
* @param {number} [opts.zombieTime] - Time in milliseconds, after this period of time - task will be interpreted as "zombie". This parameter allows to rescue task from "zombie mode" in case when: `ready()` wasn't called, exception during runtime was thrown, or caused by bad logic
42+
* @param {function} [opts.onExecuted] - Informational hook, called when task is finished, see readme for more details
43+
* @param {number} [opts.minRevolvingDelay] - Minimum revolving delay — the minimum delay between tasks executions in milliseconds
44+
* @param {number} [opts.maxRevolvingDelay] - Maximum revolving delay — the maximum delay between tasks executions in milliseconds
45+
*/
46+
constructor(opts?: JoSkOption);
47+
debug: boolean;
48+
onError: false | OnErrorFunc;
49+
autoClear: boolean;
50+
zombieTime: number;
51+
onExecuted: false | OnExecutedFunc;
52+
isDestroyed: boolean;
53+
minRevolvingDelay: number;
54+
maxRevolvingDelay: number;
55+
nextRevolutionTimeout: number;
56+
tasks: {};
57+
_debug: (...args: any[]) => void;
58+
adapter: any;
59+
/**
60+
* @async
61+
* @memberOf JoSk
62+
* @name ping
63+
* @description Check package readiness and connection to Storage
64+
* @returns {Promise<object>}
65+
* @throws {mix}
66+
*/
67+
ping(): Promise<unknown>;
68+
/**
69+
* @async
70+
* @memberOf JoSk
71+
* Create recurring task (loop)
72+
* @name setInterval
73+
* @param {function} func - Function (task) to execute
74+
* @param {number} delay - Delay between task execution in milliseconds
75+
* @param {string} uid - Unique function (task) identification as a string
76+
* @returns {Promise<string>} - Timer ID
77+
*/
78+
setInterval(func: AsyncTaskFunc | SyncNextTaskFunc, delay: number, uid: string): Promise<string>;
79+
/**
80+
* @async
81+
* @memberOf JoSk
82+
* Create delayed task
83+
* @name setTimeout
84+
* @param {function} func - Function (task) to execute
85+
* @param {number} delay - Delay before task execution in milliseconds
86+
* @param {string} uid - Unique function (task) identification as a string
87+
* @returns {Promise<string>} - Timer ID
88+
*/
89+
setTimeout(func: AsyncTaskFunc | SyncTaskFunc, delay: number, uid: string): Promise<string>;
90+
/**
91+
* @async
92+
* @memberOf JoSk
93+
* Create task, which would get executed immediately and only once across multi-server setup
94+
* @name setImmediate
95+
* @param {function} func - Function (task) to execute
96+
* @param {string} uid - Unique function (task) identification as a string
97+
* @returns {Promise<string>} - Timer ID
98+
*/
99+
setImmediate(func: AsyncTaskFunc | SyncTaskFunc, uid: string): Promise<string>;
100+
/**
101+
* @async
102+
* @memberOf JoSk
103+
* Cancel (abort) current interval timer.
104+
* Must be called in a separate event loop from `.setInterval()`
105+
* @name clearInterval
106+
* @param {string|Promise<string>} timerId - Unique function (task) identification as a string, returned from `.setInterval()`
107+
* @param {function} [callback] - optional callback
108+
* @returns {Promise<boolean>} - `true` if task cleared, `false` if task doesn't exist
109+
*/
110+
clearInterval(timerId: string | Promise<string>): Promise<boolean>;
111+
/**
112+
* @async
113+
* @memberOf JoSk
114+
* Cancel (abort) current timeout timer.
115+
* Must be called in a separate event loop from `.setTimeout()`
116+
* @name clearTimeout
117+
* @param {string|Promise<string>} timerId - Unique function (task) identification as a string, returned from `.setTimeout()`
118+
* @param {function} [callback] - optional callback
119+
* @returns {Promise<boolean>} - `true` if task cleared, `false` if task doesn't exist
120+
*/
121+
clearTimeout(timerId: string | Promise<string>): Promise<boolean>;
122+
/**
123+
* @memberOf JoSk
124+
* Destroy JoSk instance and stop all tasks
125+
* @name destroy
126+
* @returns {boolean} - `true` if instance successfully destroyed, `false` if instance already destroyed
127+
*/
128+
destroy(): boolean;
129+
__checkState(): boolean;
130+
__remove(timerId: string): Promise<any>;
131+
__add(uid: string, isInterval: boolean, delay: number): Promise<void>;
132+
__execute(task: unknown): Promise<void>;
133+
__iterate(): Promise<void>;
134+
__tick(): void;
135+
__errorHandler(error: unknown, title: string, description: string, uid: string): void;
136+
}
137+
138+
export interface MongoAdapterOption {
139+
db: Db;
140+
lockCollectionName?: string;
141+
prefix?: string;
142+
resetOnInit?: boolean;
143+
}
144+
145+
/** Class representing MongoDB adapter for JoSk */
146+
export class MongoAdapter {
147+
/**
148+
* Create a MongoAdapter instance
149+
* @param {JoSk} joskInstance - JoSk instance
150+
* @param {object} opts - configuration object
151+
* @param {Db} opts.db - Required, Mongo's `Db` instance, like one returned from `MongoClient#db()` method
152+
* @param {string} [opts.lockCollectionName] - custom "lock" collection name
153+
* @param {string} [opts.prefix] - prefix for scope isolation; use when creating multiple JoSK instances within the single application
154+
* @param {boolean} [opts.resetOnInit] - Make sure all old tasks is completed before setting a new one, see readme for more details
155+
*/
156+
constructor(opts?: MongoAdapterOption);
157+
name: string;
158+
prefix: string;
159+
lockCollectionName: string;
160+
resetOnInit: boolean;
161+
db: Db;
162+
uniqueName: string;
163+
collection: any;
164+
lockCollection: any;
165+
/**
166+
* @async
167+
* @memberOf MongoAdapter
168+
* @name ping
169+
* @description Check connection to MongoDB
170+
* @returns {Promise<object>}
171+
*/
172+
ping(): Promise<unknown>;
173+
acquireLock(): Promise<boolean>;
174+
releaseLock(): Promise<void>;
175+
remove(uid: string): Promise<boolean>;
176+
add(uid: string, isInterval: boolean, delay: number): Promise<boolean>;
177+
update(task: unknown, nextExecuteAt: Date): Promise<boolean>;
178+
iterate(nextExecuteAt: Date): Promise<void>;
179+
}
180+
181+
export interface RedisAdapterOption {
182+
client: RedisClient;
183+
lockCollectionName?: string;
184+
prefix?: string;
185+
resetOnInit?: boolean;
186+
}
187+
188+
/** Class representing Redis adapter for JoSk */
189+
export class RedisAdapter {
190+
/**
191+
* Create a RedisAdapter instance
192+
* @param {object} opts - configuration object
193+
* @param {RedisClient} opts.client - Required, Redis'es `RedisClient` instance, like one returned from `await redis.createClient().connect()` method
194+
* @param {string} [opts.lockCollectionName] - custom "lock" collection name
195+
* @param {string} [opts.prefix] - prefix for scope isolation; use when creating multiple JoSK instances within the single application
196+
* @param {boolean} [opts.resetOnInit] - Make sure all old tasks is completed before setting a new one, see readme for more details
197+
*/
198+
constructor(opts?: RedisAdapterOption);
199+
name: string;
200+
prefix: string;
201+
uniqueName: string;
202+
lockKey: string;
203+
resetOnInit: boolean;
204+
client: RedisClient;
205+
/**
206+
* @async
207+
* @memberOf RedisAdapter
208+
* @name ping
209+
* @description Check connection to Redis
210+
* @returns {Promise<object>}
211+
*/
212+
ping(): Promise<unknown>;
213+
acquireLock(): Promise<boolean>;
214+
releaseLock(): Promise<void>;
215+
remove(uid: string): Promise<boolean>;
216+
add(uid: string, isInterval: boolean, delay: number): Promise<boolean>;
217+
update(task: unknown, nextExecuteAt: Date): Promise<boolean>;
218+
iterate(nextExecuteAt: Date): Promise<void>;
219+
__getTaskKey(uid: string): string;
220+
}

‎index.d.ts

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
interface ErrorDetails {
2+
description: string
3+
error: Error
4+
uid: null | string
5+
task?: unknown
6+
}
7+
8+
interface ExecutedDetails {
9+
uid: string
10+
date: Date
11+
delay: number
12+
timestamp: number
13+
}
14+
15+
type OnErrorFunc = (title: string, details: ErrorDetails) => void
16+
type OnExecutedFunc = (uid: string, details: ExecutedDetails) => void
17+
type AsyncTaskFunc = () => Promise<void>
18+
type SyncTaskFunc = () => void
19+
type SyncNextTaskFunc = (ready: (next?: Date) => void) => void
20+
21+
export interface JoSkOption {
22+
debug?: boolean;
23+
onError?: OnErrorFunc;
24+
autoClear?: boolean;
25+
zombieTime?: number;
26+
onExecuted?: OnExecutedFunc;
27+
minRevolvingDelay?: number;
28+
maxRevolvingDelay?: number;
29+
}
30+
31+
/** Class representing a JoSk task runner (cron). */
32+
export class JoSk {
33+
/**
34+
* Create a JoSk instance
35+
* @param {object} opts - configuration object
36+
* @param {boolean} [opts.debug] - Enable debug logging
37+
* @param {function} [opts.onError] - Informational hook, called instead of throwing exceptions, see readme for more details
38+
* @param {boolean} [opts.autoClear] - Remove obsolete tasks (any tasks which are not found in the instance memory during runtime, but exists in the database)
39+
* @param {number} [opts.zombieTime] - Time in milliseconds, after this period of time - task will be interpreted as "zombie". This parameter allows to rescue task from "zombie mode" in case when: `ready()` wasn't called, exception during runtime was thrown, or caused by bad logic
40+
* @param {function} [opts.onExecuted] - Informational hook, called when task is finished, see readme for more details
41+
* @param {number} [opts.minRevolvingDelay] - Minimum revolving delay — the minimum delay between tasks executions in milliseconds
42+
* @param {number} [opts.maxRevolvingDelay] - Maximum revolving delay — the maximum delay between tasks executions in milliseconds
43+
*/
44+
constructor(opts?: JoSkOption);
45+
debug: boolean;
46+
onError: false | OnErrorFunc;
47+
autoClear: boolean;
48+
zombieTime: number;
49+
onExecuted: false | OnExecutedFunc;
50+
isDestroyed: boolean;
51+
minRevolvingDelay: number;
52+
maxRevolvingDelay: number;
53+
nextRevolutionTimeout: number;
54+
tasks: {};
55+
_debug: (...args: any[]) => void;
56+
adapter: any;
57+
/**
58+
* @async
59+
* @memberOf JoSk
60+
* @name ping
61+
* @description Check package readiness and connection to Storage
62+
* @returns {Promise<object>}
63+
* @throws {mix}
64+
*/
65+
ping(): Promise<unknown>;
66+
/**
67+
* @async
68+
* @memberOf JoSk
69+
* Create recurring task (loop)
70+
* @name setInterval
71+
* @param {function} func - Function (task) to execute
72+
* @param {number} delay - Delay between task execution in milliseconds
73+
* @param {string} uid - Unique function (task) identification as a string
74+
* @returns {Promise<string>} - Timer ID
75+
*/
76+
setInterval(func: AsyncTaskFunc | SyncNextTaskFunc, delay: number, uid: string): Promise<string>;
77+
/**
78+
* @async
79+
* @memberOf JoSk
80+
* Create delayed task
81+
* @name setTimeout
82+
* @param {function} func - Function (task) to execute
83+
* @param {number} delay - Delay before task execution in milliseconds
84+
* @param {string} uid - Unique function (task) identification as a string
85+
* @returns {Promise<string>} - Timer ID
86+
*/
87+
setTimeout(func: AsyncTaskFunc | SyncTaskFunc, delay: number, uid: string): Promise<string>;
88+
/**
89+
* @async
90+
* @memberOf JoSk
91+
* Create task, which would get executed immediately and only once across multi-server setup
92+
* @name setImmediate
93+
* @param {function} func - Function (task) to execute
94+
* @param {string} uid - Unique function (task) identification as a string
95+
* @returns {Promise<string>} - Timer ID
96+
*/
97+
setImmediate(func: AsyncTaskFunc | SyncTaskFunc, uid: string): Promise<string>;
98+
/**
99+
* @async
100+
* @memberOf JoSk
101+
* Cancel (abort) current interval timer.
102+
* Must be called in a separate event loop from `.setInterval()`
103+
* @name clearInterval
104+
* @param {string|Promise<string>} timerId - Unique function (task) identification as a string, returned from `.setInterval()`
105+
* @param {function} [callback] - optional callback
106+
* @returns {Promise<boolean>} - `true` if task cleared, `false` if task doesn't exist
107+
*/
108+
clearInterval(timerId: string | Promise<string>): Promise<boolean>;
109+
/**
110+
* @async
111+
* @memberOf JoSk
112+
* Cancel (abort) current timeout timer.
113+
* Must be called in a separate event loop from `.setTimeout()`
114+
* @name clearTimeout
115+
* @param {string|Promise<string>} timerId - Unique function (task) identification as a string, returned from `.setTimeout()`
116+
* @param {function} [callback] - optional callback
117+
* @returns {Promise<boolean>} - `true` if task cleared, `false` if task doesn't exist
118+
*/
119+
clearTimeout(timerId: string | Promise<string>): Promise<boolean>;
120+
/**
121+
* @memberOf JoSk
122+
* Destroy JoSk instance and stop all tasks
123+
* @name destroy
124+
* @returns {boolean} - `true` if instance successfully destroyed, `false` if instance already destroyed
125+
*/
126+
destroy(): boolean;
127+
__checkState(): boolean;
128+
__remove(timerId: any): Promise<any>;
129+
__add(uid: any, isInterval: any, delay: any): Promise<void>;
130+
__execute(task: any): Promise<void>;
131+
__iterate(): Promise<void>;
132+
__tick(): void;
133+
__errorHandler(error: any, title: any, description: any, uid: any): void;
134+
}
135+
import { MongoAdapter } from './adapters/mongo.js'
136+
import { RedisAdapter } from './adapters/redis.js'
137+
export { MongoAdapter, RedisAdapter }
138+

0 commit comments

Comments
 (0)
Please sign in to comment.