@strutvane/redis 0.0.0-stage → 0.2.0-next.0
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.
- package/LICENSE +21 -0
- package/README.md +146 -2
- package/dist/driver-DEW-Sggt.mjs +93 -0
- package/dist/driver-DEW-Sggt.mjs.map +1 -0
- package/dist/index.d.mts +628 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +47 -0
- package/dist/index.mjs.map +1 -0
- package/dist/installer.d.mts +72 -0
- package/dist/installer.d.mts.map +1 -0
- package/dist/installer.mjs +228 -0
- package/dist/installer.mjs.map +1 -0
- package/dist/keys-BeX5p2wm.d.mts +169 -0
- package/dist/keys-BeX5p2wm.d.mts.map +1 -0
- package/dist/provider.d.mts +63 -0
- package/dist/provider.d.mts.map +1 -0
- package/dist/provider.mjs +176 -0
- package/dist/provider.mjs.map +1 -0
- package/dist/queue.d.mts +102 -0
- package/dist/queue.d.mts.map +1 -0
- package/dist/queue.mjs +181 -0
- package/dist/queue.mjs.map +1 -0
- package/dist/tokens-CnThleYU.mjs +1626 -0
- package/dist/tokens-CnThleYU.mjs.map +1 -0
- package/package.json +105 -4
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { CacheManagerToken, IdempotencyStoreToken, ServiceProvider, SessionStoreToken } from "@strutvane/framework";
|
|
2
|
+
import { ClockToken, ErrorRegistryToken, LoggerToken } from "@strutvane/framework/core";
|
|
3
|
+
import { T as createRedisCacheManager, a as RedisSessionStore, b as KeySpace, c as RedisLocks, d as RedisConnection, f as PACKAGE_NAME, i as RedisRateLimiterToken, l as RedisIdempotencyStore, n as RedisKeySpaceToken, o as RedisRateLimiter, p as REDIS_ERRORS, r as RedisLocksToken, t as RedisConnectionToken, u as loadRedisEnv, v as describeSettings, y as resolveRedisSettings } from "./tokens-CnThleYU.mjs";
|
|
4
|
+
// src/lazy-logger.ts
|
|
5
|
+
/**
|
|
6
|
+
* Wrap a logger factory; the factory runs once, on the first log call.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* const logger = lazyLogger(() => app.make(LoggerToken).child({ component: 'redis' }))
|
|
10
|
+
*/
|
|
11
|
+
function lazyLogger(resolve) {
|
|
12
|
+
let logger;
|
|
13
|
+
const get = () => {
|
|
14
|
+
logger ??= resolve();
|
|
15
|
+
return logger;
|
|
16
|
+
};
|
|
17
|
+
return {
|
|
18
|
+
trace: (msg, fields) => get().trace(msg, fields),
|
|
19
|
+
debug: (msg, fields) => get().debug(msg, fields),
|
|
20
|
+
info: (msg, fields) => get().info(msg, fields),
|
|
21
|
+
warn: (msg, fields) => get().warn(msg, fields),
|
|
22
|
+
error: (msg, fields) => get().error(msg, fields),
|
|
23
|
+
fatal: (msg, fields) => get().fatal(msg, fields),
|
|
24
|
+
child: (bindings) => get().child(bindings),
|
|
25
|
+
isLevelEnabled: (level) => get().isLevelEnabled(level),
|
|
26
|
+
flush: () => get().flush()
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
// src/provider.ts
|
|
30
|
+
/**
|
|
31
|
+
* `RedisServiceProvider`: wires Redis into a Strutvane app. The installer adds it to
|
|
32
|
+
* `bootstrap/providers.ts`; nothing else is needed.
|
|
33
|
+
*
|
|
34
|
+
* **What it binds** (in `register()`, so it wins over the framework's defaults):
|
|
35
|
+
* - `RedisConnectionToken`: one lazily opened connection for the whole app (closed on shutdown);
|
|
36
|
+
* - `RedisKeySpaceToken`, `RedisLocksToken`, `RedisRateLimiterToken`;
|
|
37
|
+
* - `CacheManagerToken`: the framework's stores plus `redis` (and any `driver: 'redis'` store in
|
|
38
|
+
* `config/cache.ts`). With `CACHE_STORE=redis`, `Cache` and the `throttle` middleware count in
|
|
39
|
+
* Redis, so limits hold across every server;
|
|
40
|
+
* - `SessionStoreToken`: the Redis session store, when `SESSION_DRIVER=redis`;
|
|
41
|
+
* - `IdempotencyStoreToken`: the Redis idempotency store, when the default cache store is a Redis
|
|
42
|
+
* store (the app has declared Redis its shared state; a memory store would let a retry that
|
|
43
|
+
* reaches another server run twice).
|
|
44
|
+
*
|
|
45
|
+
* **Fails closed at boot:** a bad `REDIS_*` value stops the app (`invalid_redis_config`). It does
|
|
46
|
+
* not connect at boot: commands that never touch Redis keep working while it is down, and a
|
|
47
|
+
* request that needs it gets a 503 `redis_unavailable` (see `connection.ts`).
|
|
48
|
+
*
|
|
49
|
+
* In production it warns (once, in the log) about a plain-text connection to a non-local host
|
|
50
|
+
* and about a server without a password.
|
|
51
|
+
*
|
|
52
|
+
* @module
|
|
53
|
+
*/
|
|
54
|
+
/**
|
|
55
|
+
* The Redis service provider.
|
|
56
|
+
*
|
|
57
|
+
* @example
|
|
58
|
+
* // bootstrap/providers.ts
|
|
59
|
+
* import { RedisServiceProvider } from '@strutvane/redis/provider'
|
|
60
|
+
* const providers: readonly AnyProvider[] = [AppServiceProvider, RedisServiceProvider]
|
|
61
|
+
*/
|
|
62
|
+
var RedisServiceProvider = class extends ServiceProvider {
|
|
63
|
+
#options;
|
|
64
|
+
#connection;
|
|
65
|
+
#settings;
|
|
66
|
+
constructor(options = {}) {
|
|
67
|
+
super();
|
|
68
|
+
this.#options = options;
|
|
69
|
+
}
|
|
70
|
+
register(app) {
|
|
71
|
+
const config = app.configRepository;
|
|
72
|
+
const read = (path) => config.has(path) ? config.get(path) : void 0;
|
|
73
|
+
const env = this.#options.env ?? loadRedisEnv(app.basePath);
|
|
74
|
+
const appName = read("app.name");
|
|
75
|
+
const settings = resolveRedisSettings({
|
|
76
|
+
config: read("redis") ?? read("database.redis"),
|
|
77
|
+
env,
|
|
78
|
+
...typeof appName === "string" ? { appName } : {}
|
|
79
|
+
});
|
|
80
|
+
this.#settings = settings;
|
|
81
|
+
const root = KeySpace.root(settings.prefix);
|
|
82
|
+
const container = app.container;
|
|
83
|
+
const logger = () => container.make(LoggerToken).child({ component: "redis" });
|
|
84
|
+
const connection = () => {
|
|
85
|
+
this.#connection ??= new RedisConnection(settings, {
|
|
86
|
+
logger: logger(),
|
|
87
|
+
...this.#options.closeTimeoutMs === void 0 ? {} : { closeTimeoutMs: this.#options.closeTimeoutMs }
|
|
88
|
+
});
|
|
89
|
+
return this.#connection;
|
|
90
|
+
};
|
|
91
|
+
container.singleton(RedisConnectionToken, connection);
|
|
92
|
+
container.value(RedisKeySpaceToken, root);
|
|
93
|
+
container.singleton(RedisLocksToken, () => new RedisLocks({
|
|
94
|
+
driver: connection(),
|
|
95
|
+
space: root.area("lock")
|
|
96
|
+
}));
|
|
97
|
+
container.singleton(RedisRateLimiterToken, () => new RedisRateLimiter({
|
|
98
|
+
driver: connection(),
|
|
99
|
+
space: root.area("rate")
|
|
100
|
+
}));
|
|
101
|
+
const cache = createRedisCacheManagerLazily(app, read("cache"), connection, root, logger);
|
|
102
|
+
container.singleton(CacheManagerToken, cache.make);
|
|
103
|
+
if (read("session.driver") === "redis") {
|
|
104
|
+
const lifetimeMinutes = read("session.lifetime");
|
|
105
|
+
container.singleton(SessionStoreToken, () => new RedisSessionStore({
|
|
106
|
+
driver: connection(),
|
|
107
|
+
space: root.area("session"),
|
|
108
|
+
...typeof lifetimeMinutes === "number" ? { lifetimeSeconds: lifetimeMinutes * 60 } : {}
|
|
109
|
+
}));
|
|
110
|
+
}
|
|
111
|
+
if (cache.defaultIsRedis) container.singleton(IdempotencyStoreToken, () => new RedisIdempotencyStore({
|
|
112
|
+
driver: connection(),
|
|
113
|
+
space: root.area("idempotency")
|
|
114
|
+
}));
|
|
115
|
+
}
|
|
116
|
+
boot(app) {
|
|
117
|
+
const registry = app.make(ErrorRegistryToken);
|
|
118
|
+
for (const definition of REDIS_ERRORS) if (registry.get(definition.code) === void 0) registry.register(definition);
|
|
119
|
+
const settings = this.#settings;
|
|
120
|
+
if (settings === void 0 || app.environment !== "production") return;
|
|
121
|
+
const logger = app.make(LoggerToken).child({ component: "redis" });
|
|
122
|
+
if (!settings.tls && !isLocalHost(settings.host)) logger.warn("redis.plaintext", {
|
|
123
|
+
...describeSettings(settings),
|
|
124
|
+
hint: "Use rediss:// or REDIS_TLS=true for a Redis server on another machine."
|
|
125
|
+
});
|
|
126
|
+
if (settings.password === void 0) logger.warn("redis.no_password", {
|
|
127
|
+
...describeSettings(settings),
|
|
128
|
+
hint: "Set REDIS_PASSWORD (and an ACL user with REDIS_USERNAME) in production."
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
async shutdown() {
|
|
132
|
+
await this.#connection?.close();
|
|
133
|
+
}
|
|
134
|
+
};
|
|
135
|
+
/**
|
|
136
|
+
* A provider class with fixed options (for `bootstrap/providers.ts`, which lists classes).
|
|
137
|
+
*
|
|
138
|
+
* @example
|
|
139
|
+
* const providers = [AppServiceProvider, redisProvider({ closeTimeoutMs: 5000 })]
|
|
140
|
+
*/
|
|
141
|
+
function redisProvider(options) {
|
|
142
|
+
return class ConfiguredRedisServiceProvider extends RedisServiceProvider {
|
|
143
|
+
constructor() {
|
|
144
|
+
super(options);
|
|
145
|
+
}
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
/** The package name, as `node strut doctor` shows it. */
|
|
149
|
+
const name = PACKAGE_NAME;
|
|
150
|
+
function createRedisCacheManagerLazily(app, cacheConfig, connection, root, logger) {
|
|
151
|
+
const manager = createRedisCacheManager({
|
|
152
|
+
basePath: app.basePath,
|
|
153
|
+
clock: { now: () => app.make(ClockToken).now() },
|
|
154
|
+
config: cacheConfig,
|
|
155
|
+
driver: connection,
|
|
156
|
+
root,
|
|
157
|
+
logger: lazyLogger(logger)
|
|
158
|
+
});
|
|
159
|
+
return {
|
|
160
|
+
make: () => manager,
|
|
161
|
+
defaultIsRedis: isRedisStore(cacheConfig, manager.defaultStore)
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
function isRedisStore(cacheConfig, name) {
|
|
165
|
+
const stores = typeof cacheConfig === "object" && cacheConfig !== null ? cacheConfig.stores : void 0;
|
|
166
|
+
const entry = typeof stores === "object" && stores !== null ? stores[name] : void 0;
|
|
167
|
+
if (entry === void 0) return name === "redis";
|
|
168
|
+
if (entry === "redis") return true;
|
|
169
|
+
return typeof entry === "object" && entry !== null && entry.driver === "redis";
|
|
170
|
+
}
|
|
171
|
+
function isLocalHost(host) {
|
|
172
|
+
return host === "localhost" || host === "::1" || host.startsWith("127.");
|
|
173
|
+
}
|
|
174
|
+
export { RedisServiceProvider, name, redisProvider };
|
|
175
|
+
|
|
176
|
+
//# sourceMappingURL=provider.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"provider.mjs","names":[],"sources":["../src/lazy-logger.ts","../src/provider.ts"],"sourcesContent":["/**\n * A logger that resolves the app's logger on first use. Providers build services in `register()`,\n * before the app's logger may be bound (a provider can replace it), so they hold this instead.\n *\n * @module\n */\nimport type { Logger } from '@strutvane/framework/contracts'\n\n/**\n * Wrap a logger factory; the factory runs once, on the first log call.\n *\n * @example\n * const logger = lazyLogger(() => app.make(LoggerToken).child({ component: 'redis' }))\n */\nexport function lazyLogger(resolve: () => Logger): Logger {\n let logger: Logger | undefined\n const get = (): Logger => {\n logger ??= resolve()\n return logger\n }\n return {\n trace: (msg, fields) => get().trace(msg, fields),\n debug: (msg, fields) => get().debug(msg, fields),\n info: (msg, fields) => get().info(msg, fields),\n warn: (msg, fields) => get().warn(msg, fields),\n error: (msg, fields) => get().error(msg, fields),\n fatal: (msg, fields) => get().fatal(msg, fields),\n child: (bindings) => get().child(bindings),\n isLevelEnabled: (level) => get().isLevelEnabled(level),\n flush: () => get().flush(),\n }\n}\n","/**\n * `RedisServiceProvider`: wires Redis into a Strutvane app. The installer adds it to\n * `bootstrap/providers.ts`; nothing else is needed.\n *\n * **What it binds** (in `register()`, so it wins over the framework's defaults):\n * - `RedisConnectionToken`: one lazily opened connection for the whole app (closed on shutdown);\n * - `RedisKeySpaceToken`, `RedisLocksToken`, `RedisRateLimiterToken`;\n * - `CacheManagerToken`: the framework's stores plus `redis` (and any `driver: 'redis'` store in\n * `config/cache.ts`). With `CACHE_STORE=redis`, `Cache` and the `throttle` middleware count in\n * Redis, so limits hold across every server;\n * - `SessionStoreToken`: the Redis session store, when `SESSION_DRIVER=redis`;\n * - `IdempotencyStoreToken`: the Redis idempotency store, when the default cache store is a Redis\n * store (the app has declared Redis its shared state; a memory store would let a retry that\n * reaches another server run twice).\n *\n * **Fails closed at boot:** a bad `REDIS_*` value stops the app (`invalid_redis_config`). It does\n * not connect at boot: commands that never touch Redis keep working while it is down, and a\n * request that needs it gets a 503 `redis_unavailable` (see `connection.ts`).\n *\n * In production it warns (once, in the log) about a plain-text connection to a non-local host\n * and about a server without a password.\n *\n * @module\n */\nimport {\n type Application,\n CacheManagerToken,\n IdempotencyStoreToken,\n ServiceProvider,\n SessionStoreToken,\n} from '@strutvane/framework'\nimport type { Logger } from '@strutvane/framework/contracts'\nimport { ClockToken, ErrorRegistryToken, LoggerToken } from '@strutvane/framework/core'\nimport { createRedisCacheManager } from './cache-manager.ts'\nimport { describeSettings, type RedisSettings, resolveRedisSettings } from './config.ts'\nimport { RedisConnection } from './connection.ts'\nimport { loadRedisEnv } from './env.ts'\nimport { PACKAGE_NAME, REDIS_ERRORS } from './errors.ts'\nimport { RedisIdempotencyStore } from './idempotency-store.ts'\nimport { KeySpace } from './keys.ts'\nimport { lazyLogger } from './lazy-logger.ts'\nimport { RedisLocks } from './lock.ts'\nimport { RedisRateLimiter } from './rate-limiter.ts'\nimport { RedisSessionStore } from './session-store.ts'\nimport {\n RedisConnectionToken,\n RedisKeySpaceToken,\n RedisLocksToken,\n RedisRateLimiterToken,\n} from './tokens.ts'\n\n/**\n * Options for {@link redisProvider} (tests and unusual setups; apps normally list the plain\n * {@link RedisServiceProvider}).\n *\n * @example\n * redisProvider({ env: { REDIS_URL: 'redis://127.0.0.1:6380' } })\n */\nexport interface RedisProviderOptions {\n /** The environment to read `REDIS_*` from. Default: `<app>/.env` under `process.env`. */\n readonly env?: Readonly<Record<string, string | undefined>>\n /** Passed to the connection: how long shutdown waits for pending replies. Default 2000 ms. */\n readonly closeTimeoutMs?: number\n}\n\n/**\n * The Redis service provider.\n *\n * @example\n * // bootstrap/providers.ts\n * import { RedisServiceProvider } from '@strutvane/redis/provider'\n * const providers: readonly AnyProvider[] = [AppServiceProvider, RedisServiceProvider]\n */\nexport class RedisServiceProvider extends ServiceProvider {\n readonly #options: RedisProviderOptions\n #connection: RedisConnection | undefined\n #settings: RedisSettings | undefined\n\n constructor(options: RedisProviderOptions = {}) {\n super()\n this.#options = options\n }\n\n override register(app: Application): void {\n const config = app.configRepository\n const read = (path: string): unknown => (config.has(path) ? config.get(path) : undefined)\n const env = this.#options.env ?? loadRedisEnv(app.basePath)\n const appName = read('app.name')\n const settings = resolveRedisSettings({\n config: read('redis') ?? read('database.redis'),\n env,\n ...(typeof appName === 'string' ? { appName } : {}),\n })\n this.#settings = settings\n const root = KeySpace.root(settings.prefix)\n const container = app.container\n const logger = (): Logger => container.make(LoggerToken).child({ component: 'redis' })\n const connection = (): RedisConnection => {\n this.#connection ??= new RedisConnection(settings, {\n logger: logger(),\n ...(this.#options.closeTimeoutMs === undefined\n ? {}\n : { closeTimeoutMs: this.#options.closeTimeoutMs }),\n })\n return this.#connection\n }\n\n container.singleton(RedisConnectionToken, connection)\n container.value(RedisKeySpaceToken, root)\n container.singleton(\n RedisLocksToken,\n () => new RedisLocks({ driver: connection(), space: root.area('lock') }),\n )\n container.singleton(\n RedisRateLimiterToken,\n () => new RedisRateLimiter({ driver: connection(), space: root.area('rate') }),\n )\n\n const cacheConfig = read('cache')\n const cache = createRedisCacheManagerLazily(app, cacheConfig, connection, root, logger)\n container.singleton(CacheManagerToken, cache.make)\n\n if (read('session.driver') === 'redis') {\n const lifetimeMinutes = read('session.lifetime')\n container.singleton(\n SessionStoreToken,\n () =>\n new RedisSessionStore({\n driver: connection(),\n space: root.area('session'),\n ...(typeof lifetimeMinutes === 'number'\n ? { lifetimeSeconds: lifetimeMinutes * 60 }\n : {}),\n }),\n )\n }\n\n if (cache.defaultIsRedis)\n container.singleton(\n IdempotencyStoreToken,\n () => new RedisIdempotencyStore({ driver: connection(), space: root.area('idempotency') }),\n )\n }\n\n override boot(app: Application): void {\n const registry = app.make(ErrorRegistryToken)\n for (const definition of REDIS_ERRORS)\n if (registry.get(definition.code) === undefined) registry.register(definition)\n const settings = this.#settings\n if (settings === undefined || app.environment !== 'production') return\n const logger = app.make(LoggerToken).child({ component: 'redis' })\n if (!settings.tls && !isLocalHost(settings.host))\n logger.warn('redis.plaintext', {\n ...describeSettings(settings),\n hint: 'Use rediss:// or REDIS_TLS=true for a Redis server on another machine.',\n })\n if (settings.password === undefined)\n logger.warn('redis.no_password', {\n ...describeSettings(settings),\n hint: 'Set REDIS_PASSWORD (and an ACL user with REDIS_USERNAME) in production.',\n })\n }\n\n override async shutdown(): Promise<void> {\n await this.#connection?.close()\n }\n}\n\n/**\n * A provider class with fixed options (for `bootstrap/providers.ts`, which lists classes).\n *\n * @example\n * const providers = [AppServiceProvider, redisProvider({ closeTimeoutMs: 5000 })]\n */\nexport function redisProvider(options: RedisProviderOptions): new () => RedisServiceProvider {\n return class ConfiguredRedisServiceProvider extends RedisServiceProvider {\n constructor() {\n super(options)\n }\n }\n}\n\n/** The package name, as `node strut doctor` shows it. */\nexport const name: string = PACKAGE_NAME\n\nfunction createRedisCacheManagerLazily(\n app: Application,\n cacheConfig: unknown,\n connection: () => RedisConnection,\n root: KeySpace,\n logger: () => Logger,\n): {\n readonly make: () => ReturnType<typeof createRedisCacheManager>\n readonly defaultIsRedis: boolean\n} {\n // Built eagerly once to validate the config at register time (fail closed at boot), then\n // reused: stores inside it are still created on first use.\n const manager = createRedisCacheManager({\n basePath: app.basePath,\n clock: { now: () => app.make(ClockToken).now() },\n config: cacheConfig,\n driver: connection,\n root,\n logger: lazyLogger(logger),\n })\n const defaultIsRedis = isRedisStore(cacheConfig, manager.defaultStore)\n return { make: () => manager, defaultIsRedis }\n}\n\nfunction isRedisStore(cacheConfig: unknown, name: string): boolean {\n const stores =\n typeof cacheConfig === 'object' && cacheConfig !== null\n ? (cacheConfig as { stores?: unknown }).stores\n : undefined\n const entry =\n typeof stores === 'object' && stores !== null\n ? (stores as Record<string, unknown>)[name]\n : undefined\n if (entry === undefined) return name === 'redis'\n if (entry === 'redis') return true\n return (\n typeof entry === 'object' &&\n entry !== null &&\n (entry as { driver?: unknown }).driver === 'redis'\n )\n}\n\nfunction isLocalHost(host: string): boolean {\n return host === 'localhost' || host === '::1' || host.startsWith('127.')\n}\n"],"mappings":"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"}
|
package/dist/queue.d.mts
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@strutvane/redis/queue`: **experimental** queue-driver interface and its Redis implementation,
|
|
3
|
+
* ready for framework queues (0.3). Not wired into the app until the framework defines queues.
|
|
4
|
+
*
|
|
5
|
+
* @packageDocumentation
|
|
6
|
+
*/
|
|
7
|
+
import { s as RedisDriver, t as KeySpace } from "./keys-BeX5p2wm.mjs";
|
|
8
|
+
/**
|
|
9
|
+
* **Experimental.** The queue-driver interface this package proposes for framework queues
|
|
10
|
+
* (planned for the 0.3 line, hub `docs/18` §10 "Background work"). The framework has no queue
|
|
11
|
+
* contract yet, so this lives here; when the framework defines one, this interface moves there (or
|
|
12
|
+
* adapts to it) and the Redis driver implements the framework's version. Expect breaking changes
|
|
13
|
+
* until then; nothing in the app wires it up automatically.
|
|
14
|
+
*
|
|
15
|
+
* The semantics are Laravel's: at-least-once delivery. A popped job is *reserved* for a visibility
|
|
16
|
+
* timeout; the worker acknowledges it when done, or releases it to retry later. A worker that
|
|
17
|
+
* crashes never acknowledges, so the job becomes available again when its reservation expires.
|
|
18
|
+
* Handlers must therefore be idempotent.
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* A job handed to a worker.
|
|
24
|
+
*
|
|
25
|
+
* @experimental
|
|
26
|
+
* @example
|
|
27
|
+
* const job = await driver.pop('emails')
|
|
28
|
+
* if (job) { await handle(JSON.parse(job.payload)); await driver.ack(job) }
|
|
29
|
+
*/
|
|
30
|
+
interface ReservedJob {
|
|
31
|
+
readonly id: string;
|
|
32
|
+
readonly queue: string;
|
|
33
|
+
/** The caller's serialised job (the driver never parses it). */
|
|
34
|
+
readonly payload: string;
|
|
35
|
+
/** How many times the job has been reserved, including this one. */
|
|
36
|
+
readonly attempts: number;
|
|
37
|
+
/** When the reservation runs out (ms since the epoch, server clock). */
|
|
38
|
+
readonly reservedUntil: number;
|
|
39
|
+
/** The driver's own handle for ack/release. Opaque. */
|
|
40
|
+
readonly receipt: string;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Options for {@link QueueDriver.push}.
|
|
44
|
+
*
|
|
45
|
+
* @experimental
|
|
46
|
+
* @example
|
|
47
|
+
* await driver.push('emails', payload, { delaySeconds: 60 })
|
|
48
|
+
*/
|
|
49
|
+
interface PushOptions {
|
|
50
|
+
/** Make the job available only after this many seconds. Default 0. */
|
|
51
|
+
readonly delaySeconds?: number;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* A queue backend.
|
|
55
|
+
*
|
|
56
|
+
* @experimental
|
|
57
|
+
* @example
|
|
58
|
+
* class SqsDriver implements QueueDriver { … }
|
|
59
|
+
*/
|
|
60
|
+
interface QueueDriver {
|
|
61
|
+
/** Add a job; returns its id. */
|
|
62
|
+
push(queue: string, payload: string, options?: PushOptions): Promise<string>;
|
|
63
|
+
/** Reserve the next available job, or `undefined` when the queue is empty. */
|
|
64
|
+
pop(queue: string, options?: {
|
|
65
|
+
readonly visibilitySeconds?: number;
|
|
66
|
+
}): Promise<ReservedJob | undefined>;
|
|
67
|
+
/** The job is done: remove it for good. `false` when its reservation had already expired. */
|
|
68
|
+
ack(job: ReservedJob): Promise<boolean>;
|
|
69
|
+
/** Put the job back (after `delaySeconds`) for another attempt. `false` when no longer reserved. */
|
|
70
|
+
release(job: ReservedJob, delaySeconds?: number): Promise<boolean>;
|
|
71
|
+
/** Jobs waiting, delayed and reserved. */
|
|
72
|
+
size(queue: string): Promise<number>;
|
|
73
|
+
/** Remove every job of the queue; returns how many were removed. */
|
|
74
|
+
clear(queue: string): Promise<number>;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* The Redis queue driver.
|
|
78
|
+
*
|
|
79
|
+
* @experimental
|
|
80
|
+
* @example
|
|
81
|
+
* const queue = new RedisQueueDriver({ driver: redis, space: KeySpace.root('blog:').area('queue') })
|
|
82
|
+
* await queue.push('emails', JSON.stringify({ to: 'a@example.com' }))
|
|
83
|
+
*/
|
|
84
|
+
export declare class RedisQueueDriver implements QueueDriver {
|
|
85
|
+
#private;
|
|
86
|
+
constructor(options: {
|
|
87
|
+
readonly driver: RedisDriver;
|
|
88
|
+
readonly space: KeySpace;
|
|
89
|
+
/** Default reservation length. Default 90 s (Laravel's `retry_after`). */
|
|
90
|
+
readonly visibilitySeconds?: number;
|
|
91
|
+
});
|
|
92
|
+
push(queue: string, payload: string, options?: PushOptions): Promise<string>;
|
|
93
|
+
pop(queue: string, options?: {
|
|
94
|
+
readonly visibilitySeconds?: number;
|
|
95
|
+
}): Promise<ReservedJob | undefined>;
|
|
96
|
+
ack(job: ReservedJob): Promise<boolean>;
|
|
97
|
+
release(job: ReservedJob, delaySeconds?: number): Promise<boolean>;
|
|
98
|
+
size(queue: string): Promise<number>;
|
|
99
|
+
clear(queue: string): Promise<number>;
|
|
100
|
+
}
|
|
101
|
+
export type { PushOptions, QueueDriver, ReservedJob };
|
|
102
|
+
//# sourceMappingURL=queue.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"queue.d.mts","names":[],"sources":["../src/queue/contract.ts","../src/queue/redis-queue.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuBiB;WACN;WACA;;WAEA;;WAEA;;WAEA;;WAEA;;;;;;;;;UAUM;;WAEN;;;;;;;;;UAUM;;EAEf,KAAK,eAAe,iBAAiB,UAAU,cAAc;;EAE7D,IACE,eACA;aAAqB;MACpB,QAAQ;;EAEX,IAAI,KAAK,cAAc;;EAEvB,QAAQ,KAAK,aAAa,wBAAwB;;EAElD,KAAK,gBAAgB;;EAErB,MAAM,gBAAgB;;;;;;;;;;qBCSX,4BAA4B;;EAKvC,YAAY;aACD,QAAQ;aACR,OAAO;;aAEP;;EAOL,KAAK,eAAe,iBAAiB,UAAS,cAAmB;EAcjE,IACJ,eACA;aAAoB;MACnB,QAAQ;EA0BL,IAAI,KAAK,cAAc;EAKvB,QAAQ,KAAK,aAAa,wBAAmB;EAc7C,KAAK,gBAAgB;EAUrB,MAAM,gBAAgB"}
|
package/dist/queue.mjs
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import { randomBytes } from "node:crypto";
|
|
2
|
+
import { i as defineLua, n as asInteger, r as asNullableString, t as asArray } from "./driver-DEW-Sggt.mjs";
|
|
3
|
+
// src/queue/redis-queue.ts
|
|
4
|
+
/**
|
|
5
|
+
* **Experimental.** A Redis implementation of the proposed {@link QueueDriver}, laid out like
|
|
6
|
+
* Laravel's Redis queue:
|
|
7
|
+
*
|
|
8
|
+
* - `<prefix>queue:<name>`: a list of waiting jobs;
|
|
9
|
+
* - `<prefix>queue:<name>:delayed`: a sorted set of delayed jobs, scored by when they are due;
|
|
10
|
+
* - `<prefix>queue:<name>:reserved`: a sorted set of reserved jobs, scored by when the
|
|
11
|
+
* reservation runs out.
|
|
12
|
+
*
|
|
13
|
+
* `pop` is one Lua script: it moves due delayed jobs and expired reservations back to the list,
|
|
14
|
+
* then reserves the head, so two workers never get the same job, and a crashed worker's job comes
|
|
15
|
+
* back by itself. Time is the server's (`TIME`), so workers with skewed clocks agree.
|
|
16
|
+
*
|
|
17
|
+
* Polling only (no `BLPOP`): a blocking pop would hold the app's shared connection. The framework's
|
|
18
|
+
* future worker decides how often to poll.
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
const QUEUE_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
|
|
23
|
+
const MAX_PAYLOAD_BYTES = 1048576;
|
|
24
|
+
const PUSH_DELAYED = defineLua(`
|
|
25
|
+
local t = redis.call('TIME')
|
|
26
|
+
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
|
|
27
|
+
redis.call('ZADD', KEYS[1], now + tonumber(ARGV[2]), ARGV[1])
|
|
28
|
+
return 1
|
|
29
|
+
`);
|
|
30
|
+
const POP = defineLua(`
|
|
31
|
+
local t = redis.call('TIME')
|
|
32
|
+
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
|
|
33
|
+
for _, set in ipairs({KEYS[2], KEYS[3]}) do
|
|
34
|
+
local due = redis.call('ZRANGEBYSCORE', set, '-inf', now, 'LIMIT', 0, 100)
|
|
35
|
+
for _, job in ipairs(due) do
|
|
36
|
+
redis.call('ZREM', set, job)
|
|
37
|
+
redis.call('RPUSH', KEYS[1], job)
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
local job = redis.call('LPOP', KEYS[1])
|
|
41
|
+
if not job then return false end
|
|
42
|
+
local decoded = cjson.decode(job)
|
|
43
|
+
decoded['attempts'] = (tonumber(decoded['attempts']) or 0) + 1
|
|
44
|
+
local reserved = cjson.encode(decoded)
|
|
45
|
+
local until_ms = now + tonumber(ARGV[1])
|
|
46
|
+
redis.call('ZADD', KEYS[3], until_ms, reserved)
|
|
47
|
+
return {reserved, tostring(until_ms)}
|
|
48
|
+
`);
|
|
49
|
+
const RELEASE = defineLua(`
|
|
50
|
+
if redis.call('ZREM', KEYS[2], ARGV[1]) == 0 then return 0 end
|
|
51
|
+
if tonumber(ARGV[2]) <= 0 then
|
|
52
|
+
redis.call('RPUSH', KEYS[1], ARGV[1])
|
|
53
|
+
else
|
|
54
|
+
local t = redis.call('TIME')
|
|
55
|
+
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
|
|
56
|
+
redis.call('ZADD', KEYS[3], now + tonumber(ARGV[2]), ARGV[1])
|
|
57
|
+
end
|
|
58
|
+
return 1
|
|
59
|
+
`);
|
|
60
|
+
/**
|
|
61
|
+
* The Redis queue driver.
|
|
62
|
+
*
|
|
63
|
+
* @experimental
|
|
64
|
+
* @example
|
|
65
|
+
* const queue = new RedisQueueDriver({ driver: redis, space: KeySpace.root('blog:').area('queue') })
|
|
66
|
+
* await queue.push('emails', JSON.stringify({ to: 'a@example.com' }))
|
|
67
|
+
*/
|
|
68
|
+
var RedisQueueDriver = class {
|
|
69
|
+
#driver;
|
|
70
|
+
#space;
|
|
71
|
+
#visibilityMs;
|
|
72
|
+
constructor(options) {
|
|
73
|
+
this.#driver = options.driver;
|
|
74
|
+
this.#space = options.space;
|
|
75
|
+
this.#visibilityMs = seconds(options.visibilitySeconds ?? 90, "visibilitySeconds");
|
|
76
|
+
}
|
|
77
|
+
async push(queue, payload, options = {}) {
|
|
78
|
+
const keys = this.#keys(queue);
|
|
79
|
+
if (typeof payload !== "string" || Buffer.byteLength(payload, "utf8") > MAX_PAYLOAD_BYTES) throw new RangeError(`A job payload must be a string of at most ${MAX_PAYLOAD_BYTES} bytes.`);
|
|
80
|
+
const id = randomBytes(12).toString("base64url");
|
|
81
|
+
const envelope = JSON.stringify({
|
|
82
|
+
id,
|
|
83
|
+
attempts: 0,
|
|
84
|
+
payload
|
|
85
|
+
});
|
|
86
|
+
const delayMs = options.delaySeconds === void 0 ? 0 : seconds(options.delaySeconds, "delaySeconds", true);
|
|
87
|
+
if (delayMs > 0) await this.#driver.script(PUSH_DELAYED, [keys.delayed], [envelope, String(delayMs)]);
|
|
88
|
+
else await this.#driver.command([
|
|
89
|
+
"RPUSH",
|
|
90
|
+
keys.ready,
|
|
91
|
+
envelope
|
|
92
|
+
]);
|
|
93
|
+
return id;
|
|
94
|
+
}
|
|
95
|
+
async pop(queue, options = {}) {
|
|
96
|
+
const keys = this.#keys(queue);
|
|
97
|
+
const visibility = options.visibilitySeconds === void 0 ? this.#visibilityMs : seconds(options.visibilitySeconds, "visibilitySeconds");
|
|
98
|
+
const reply = await this.#driver.script(POP, [
|
|
99
|
+
keys.ready,
|
|
100
|
+
keys.delayed,
|
|
101
|
+
keys.reserved
|
|
102
|
+
], [String(visibility)]);
|
|
103
|
+
if (reply === null || reply === void 0) return void 0;
|
|
104
|
+
const [receiptReply, untilReply] = asArray(reply);
|
|
105
|
+
const receipt = asNullableString(receiptReply);
|
|
106
|
+
if (receipt === null) return void 0;
|
|
107
|
+
const envelope = parseEnvelope(receipt);
|
|
108
|
+
return {
|
|
109
|
+
id: envelope.id,
|
|
110
|
+
queue,
|
|
111
|
+
payload: envelope.payload,
|
|
112
|
+
attempts: envelope.attempts,
|
|
113
|
+
reservedUntil: asInteger(untilReply),
|
|
114
|
+
receipt
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
async ack(job) {
|
|
118
|
+
const keys = this.#keys(job.queue);
|
|
119
|
+
return asInteger(await this.#driver.command([
|
|
120
|
+
"ZREM",
|
|
121
|
+
keys.reserved,
|
|
122
|
+
job.receipt
|
|
123
|
+
])) === 1;
|
|
124
|
+
}
|
|
125
|
+
async release(job, delaySeconds = 0) {
|
|
126
|
+
const keys = this.#keys(job.queue);
|
|
127
|
+
const delayMs = seconds(delaySeconds, "delaySeconds", true);
|
|
128
|
+
return asInteger(await this.#driver.script(RELEASE, [
|
|
129
|
+
keys.ready,
|
|
130
|
+
keys.reserved,
|
|
131
|
+
keys.delayed
|
|
132
|
+
], [job.receipt, String(delayMs)])) === 1;
|
|
133
|
+
}
|
|
134
|
+
async size(queue) {
|
|
135
|
+
const keys = this.#keys(queue);
|
|
136
|
+
const [ready, delayed, reserved] = await Promise.all([
|
|
137
|
+
this.#driver.command(["LLEN", keys.ready]),
|
|
138
|
+
this.#driver.command(["ZCARD", keys.delayed]),
|
|
139
|
+
this.#driver.command(["ZCARD", keys.reserved])
|
|
140
|
+
]);
|
|
141
|
+
return asInteger(ready) + asInteger(delayed) + asInteger(reserved);
|
|
142
|
+
}
|
|
143
|
+
async clear(queue) {
|
|
144
|
+
const size = await this.size(queue);
|
|
145
|
+
const keys = this.#keys(queue);
|
|
146
|
+
await this.#driver.command([
|
|
147
|
+
"UNLINK",
|
|
148
|
+
keys.ready,
|
|
149
|
+
keys.delayed,
|
|
150
|
+
keys.reserved
|
|
151
|
+
]);
|
|
152
|
+
return size;
|
|
153
|
+
}
|
|
154
|
+
#keys(queue) {
|
|
155
|
+
if (!QUEUE_NAME.test(queue)) throw new TypeError("A queue name may only contain letters, digits, _ . and - (1 to 64 characters).");
|
|
156
|
+
const ready = this.#space.key(queue);
|
|
157
|
+
return {
|
|
158
|
+
ready,
|
|
159
|
+
delayed: `${ready}:delayed`,
|
|
160
|
+
reserved: `${ready}:reserved`
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
};
|
|
164
|
+
function seconds(value, name, allowZero = false) {
|
|
165
|
+
if (!Number.isFinite(value) || value < 0 || !allowZero && value === 0) throw new RangeError(`${name} must be a number of seconds ${allowZero ? "(0 or more)" : "above 0"}.`);
|
|
166
|
+
return Math.round(value * 1e3);
|
|
167
|
+
}
|
|
168
|
+
function parseEnvelope(raw) {
|
|
169
|
+
const value = JSON.parse(raw);
|
|
170
|
+
if (typeof value !== "object" || value === null) throw new TypeError("A queued job is corrupt.");
|
|
171
|
+
const { id, attempts, payload } = value;
|
|
172
|
+
if (typeof id !== "string" || typeof payload !== "string" || typeof attempts !== "number") throw new TypeError("A queued job is corrupt.");
|
|
173
|
+
return {
|
|
174
|
+
id,
|
|
175
|
+
attempts,
|
|
176
|
+
payload
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
export { RedisQueueDriver };
|
|
180
|
+
|
|
181
|
+
//# sourceMappingURL=queue.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"queue.mjs","names":[],"sources":["../src/queue/redis-queue.ts"],"sourcesContent":["/**\n * **Experimental.** A Redis implementation of the proposed {@link QueueDriver}, laid out like\n * Laravel's Redis queue:\n *\n * - `<prefix>queue:<name>`: a list of waiting jobs;\n * - `<prefix>queue:<name>:delayed`: a sorted set of delayed jobs, scored by when they are due;\n * - `<prefix>queue:<name>:reserved`: a sorted set of reserved jobs, scored by when the\n * reservation runs out.\n *\n * `pop` is one Lua script: it moves due delayed jobs and expired reservations back to the list,\n * then reserves the head, so two workers never get the same job, and a crashed worker's job comes\n * back by itself. Time is the server's (`TIME`), so workers with skewed clocks agree.\n *\n * Polling only (no `BLPOP`): a blocking pop would hold the app's shared connection. The framework's\n * future worker decides how often to poll.\n *\n * @module\n */\nimport { randomBytes } from 'node:crypto'\nimport { asArray, asInteger, asNullableString, defineLua, type RedisDriver } from '../driver.ts'\nimport type { KeySpace } from '../keys.ts'\nimport type { PushOptions, QueueDriver, ReservedJob } from './contract.ts'\n\nconst QUEUE_NAME = /^[A-Za-z0-9_.-]{1,64}$/\nconst MAX_PAYLOAD_BYTES = 1024 * 1024\n\nconst PUSH_DELAYED = defineLua(`\nlocal t = redis.call('TIME')\nlocal now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nredis.call('ZADD', KEYS[1], now + tonumber(ARGV[2]), ARGV[1])\nreturn 1\n`)\n\nconst POP = defineLua(`\nlocal t = redis.call('TIME')\nlocal now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nfor _, set in ipairs({KEYS[2], KEYS[3]}) do\n local due = redis.call('ZRANGEBYSCORE', set, '-inf', now, 'LIMIT', 0, 100)\n for _, job in ipairs(due) do\n redis.call('ZREM', set, job)\n redis.call('RPUSH', KEYS[1], job)\n end\nend\nlocal job = redis.call('LPOP', KEYS[1])\nif not job then return false end\nlocal decoded = cjson.decode(job)\ndecoded['attempts'] = (tonumber(decoded['attempts']) or 0) + 1\nlocal reserved = cjson.encode(decoded)\nlocal until_ms = now + tonumber(ARGV[1])\nredis.call('ZADD', KEYS[3], until_ms, reserved)\nreturn {reserved, tostring(until_ms)}\n`)\n\nconst RELEASE = defineLua(`\nif redis.call('ZREM', KEYS[2], ARGV[1]) == 0 then return 0 end\nif tonumber(ARGV[2]) <= 0 then\n redis.call('RPUSH', KEYS[1], ARGV[1])\nelse\n local t = redis.call('TIME')\n local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\n redis.call('ZADD', KEYS[3], now + tonumber(ARGV[2]), ARGV[1])\nend\nreturn 1\n`)\n\ninterface Envelope {\n readonly id: string\n readonly attempts: number\n readonly payload: string\n}\n\n/**\n * The Redis queue driver.\n *\n * @experimental\n * @example\n * const queue = new RedisQueueDriver({ driver: redis, space: KeySpace.root('blog:').area('queue') })\n * await queue.push('emails', JSON.stringify({ to: 'a@example.com' }))\n */\nexport class RedisQueueDriver implements QueueDriver {\n readonly #driver: RedisDriver\n readonly #space: KeySpace\n readonly #visibilityMs: number\n\n constructor(options: {\n readonly driver: RedisDriver\n readonly space: KeySpace\n /** Default reservation length. Default 90 s (Laravel's `retry_after`). */\n readonly visibilitySeconds?: number\n }) {\n this.#driver = options.driver\n this.#space = options.space\n this.#visibilityMs = seconds(options.visibilitySeconds ?? 90, 'visibilitySeconds')\n }\n\n async push(queue: string, payload: string, options: PushOptions = {}): Promise<string> {\n const keys = this.#keys(queue)\n if (typeof payload !== 'string' || Buffer.byteLength(payload, 'utf8') > MAX_PAYLOAD_BYTES)\n throw new RangeError(`A job payload must be a string of at most ${MAX_PAYLOAD_BYTES} bytes.`)\n const id = randomBytes(12).toString('base64url')\n const envelope = JSON.stringify({ id, attempts: 0, payload } satisfies Envelope)\n const delayMs =\n options.delaySeconds === undefined ? 0 : seconds(options.delaySeconds, 'delaySeconds', true)\n if (delayMs > 0)\n await this.#driver.script(PUSH_DELAYED, [keys.delayed], [envelope, String(delayMs)])\n else await this.#driver.command(['RPUSH', keys.ready, envelope])\n return id\n }\n\n async pop(\n queue: string,\n options: { readonly visibilitySeconds?: number } = {},\n ): Promise<ReservedJob | undefined> {\n const keys = this.#keys(queue)\n const visibility =\n options.visibilitySeconds === undefined\n ? this.#visibilityMs\n : seconds(options.visibilitySeconds, 'visibilitySeconds')\n const reply = await this.#driver.script(\n POP,\n [keys.ready, keys.delayed, keys.reserved],\n [String(visibility)],\n )\n if (reply === null || reply === undefined) return undefined\n const [receiptReply, untilReply] = asArray(reply)\n const receipt = asNullableString(receiptReply)\n if (receipt === null) return undefined\n const envelope = parseEnvelope(receipt)\n return {\n id: envelope.id,\n queue,\n payload: envelope.payload,\n attempts: envelope.attempts,\n reservedUntil: asInteger(untilReply),\n receipt,\n }\n }\n\n async ack(job: ReservedJob): Promise<boolean> {\n const keys = this.#keys(job.queue)\n return asInteger(await this.#driver.command(['ZREM', keys.reserved, job.receipt])) === 1\n }\n\n async release(job: ReservedJob, delaySeconds = 0): Promise<boolean> {\n const keys = this.#keys(job.queue)\n const delayMs = seconds(delaySeconds, 'delaySeconds', true)\n return (\n asInteger(\n await this.#driver.script(\n RELEASE,\n [keys.ready, keys.reserved, keys.delayed],\n [job.receipt, String(delayMs)],\n ),\n ) === 1\n )\n }\n\n async size(queue: string): Promise<number> {\n const keys = this.#keys(queue)\n const [ready, delayed, reserved] = await Promise.all([\n this.#driver.command(['LLEN', keys.ready]),\n this.#driver.command(['ZCARD', keys.delayed]),\n this.#driver.command(['ZCARD', keys.reserved]),\n ])\n return asInteger(ready) + asInteger(delayed) + asInteger(reserved)\n }\n\n async clear(queue: string): Promise<number> {\n const size = await this.size(queue)\n const keys = this.#keys(queue)\n await this.#driver.command(['UNLINK', keys.ready, keys.delayed, keys.reserved])\n return size\n }\n\n #keys(queue: string): {\n readonly ready: string\n readonly delayed: string\n readonly reserved: string\n } {\n if (!QUEUE_NAME.test(queue))\n throw new TypeError(\n 'A queue name may only contain letters, digits, _ . and - (1 to 64 characters).',\n )\n const ready = this.#space.key(queue)\n return { ready, delayed: `${ready}:delayed`, reserved: `${ready}:reserved` }\n }\n}\n\nfunction seconds(value: number, name: string, allowZero = false): number {\n if (!Number.isFinite(value) || value < 0 || (!allowZero && value === 0))\n throw new RangeError(\n `${name} must be a number of seconds ${allowZero ? '(0 or more)' : 'above 0'}.`,\n )\n return Math.round(value * 1000)\n}\n\nfunction parseEnvelope(raw: string): Envelope {\n const value: unknown = JSON.parse(raw)\n if (typeof value !== 'object' || value === null) throw new TypeError('A queued job is corrupt.')\n const { id, attempts, payload } = value as Record<string, unknown>\n if (typeof id !== 'string' || typeof payload !== 'string' || typeof attempts !== 'number')\n throw new TypeError('A queued job is corrupt.')\n return { id, attempts, payload }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,MAAM,aAAa;AACnB,MAAM,oBAAoB;AAE1B,MAAM,eAAe,UAAU;;;;;CAK9B;AAED,MAAM,MAAM,UAAU;;;;;;;;;;;;;;;;;;CAkBrB;AAED,MAAM,UAAU,UAAU;;;;;;;;;;CAUzB;;;;;;;;;AAgBD,IAAa,mBAAb,MAAqD;CAC1C;CACA;CACA;CAET,YAAY,SAKT;EACD,KAAK,UAAU,QAAQ;EACvB,KAAK,SAAS,QAAQ;EACtB,KAAK,gBAAgB,QAAQ,QAAQ,qBAAqB,IAAI,mBAAmB;CACnF;CAEA,MAAM,KAAK,OAAe,SAAiB,UAAuB,CAAC,GAAoB;EACrF,MAAM,OAAO,KAAK,MAAM,KAAK;EAC7B,IAAI,OAAO,YAAY,YAAY,OAAO,WAAW,SAAS,MAAM,IAAI,mBACtE,MAAM,IAAI,WAAW,6CAA6C,kBAAkB,QAAQ;EAC9F,MAAM,KAAK,YAAY,EAAE,CAAC,CAAC,SAAS,WAAW;EAC/C,MAAM,WAAW,KAAK,UAAU;GAAE;GAAI,UAAU;GAAG;EAAQ,CAAoB;EAC/E,MAAM,UACJ,QAAQ,iBAAiB,KAAA,IAAY,IAAI,QAAQ,QAAQ,cAAc,gBAAgB,IAAI;EAC7F,IAAI,UAAU,GACZ,MAAM,KAAK,QAAQ,OAAO,cAAc,CAAC,KAAK,OAAO,GAAG,CAAC,UAAU,OAAO,OAAO,CAAC,CAAC;OAChF,MAAM,KAAK,QAAQ,QAAQ;GAAC;GAAS,KAAK;GAAO;EAAQ,CAAC;EAC/D,OAAO;CACT;CAEA,MAAM,IACJ,OACA,UAAmD,CAAC,GAClB;EAClC,MAAM,OAAO,KAAK,MAAM,KAAK;EAC7B,MAAM,aACJ,QAAQ,sBAAsB,KAAA,IAC1B,KAAK,gBACL,QAAQ,QAAQ,mBAAmB,mBAAmB;EAC5D,MAAM,QAAQ,MAAM,KAAK,QAAQ,OAC/B,KACA;GAAC,KAAK;GAAO,KAAK;GAAS,KAAK;EAAQ,GACxC,CAAC,OAAO,UAAU,CAAC,CACrB;EACA,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,OAAO,KAAA;EAClD,MAAM,CAAC,cAAc,cAAc,QAAQ,KAAK;EAChD,MAAM,UAAU,iBAAiB,YAAY;EAC7C,IAAI,YAAY,MAAM,OAAO,KAAA;EAC7B,MAAM,WAAW,cAAc,OAAO;EACtC,OAAO;GACL,IAAI,SAAS;GACb;GACA,SAAS,SAAS;GAClB,UAAU,SAAS;GACnB,eAAe,UAAU,UAAU;GACnC;EACF;CACF;CAEA,MAAM,IAAI,KAAoC;EAC5C,MAAM,OAAO,KAAK,MAAM,IAAI,KAAK;EACjC,OAAO,UAAU,MAAM,KAAK,QAAQ,QAAQ;GAAC;GAAQ,KAAK;GAAU,IAAI;EAAO,CAAC,CAAC,MAAM;CACzF;CAEA,MAAM,QAAQ,KAAkB,eAAe,GAAqB;EAClE,MAAM,OAAO,KAAK,MAAM,IAAI,KAAK;EACjC,MAAM,UAAU,QAAQ,cAAc,gBAAgB,IAAI;EAC1D,OACE,UACE,MAAM,KAAK,QAAQ,OACjB,SACA;GAAC,KAAK;GAAO,KAAK;GAAU,KAAK;EAAO,GACxC,CAAC,IAAI,SAAS,OAAO,OAAO,CAAC,CAC/B,CACF,MAAM;CAEV;CAEA,MAAM,KAAK,OAAgC;EACzC,MAAM,OAAO,KAAK,MAAM,KAAK;EAC7B,MAAM,CAAC,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI;GACnD,KAAK,QAAQ,QAAQ,CAAC,QAAQ,KAAK,KAAK,CAAC;GACzC,KAAK,QAAQ,QAAQ,CAAC,SAAS,KAAK,OAAO,CAAC;GAC5C,KAAK,QAAQ,QAAQ,CAAC,SAAS,KAAK,QAAQ,CAAC;EAC/C,CAAC;EACD,OAAO,UAAU,KAAK,IAAI,UAAU,OAAO,IAAI,UAAU,QAAQ;CACnE;CAEA,MAAM,MAAM,OAAgC;EAC1C,MAAM,OAAO,MAAM,KAAK,KAAK,KAAK;EAClC,MAAM,OAAO,KAAK,MAAM,KAAK;EAC7B,MAAM,KAAK,QAAQ,QAAQ;GAAC;GAAU,KAAK;GAAO,KAAK;GAAS,KAAK;EAAQ,CAAC;EAC9E,OAAO;CACT;CAEA,MAAM,OAIJ;EACA,IAAI,CAAC,WAAW,KAAK,KAAK,GACxB,MAAM,IAAI,UACR,gFACF;EACF,MAAM,QAAQ,KAAK,OAAO,IAAI,KAAK;EACnC,OAAO;GAAE;GAAO,SAAS,GAAG,MAAM;GAAW,UAAU,GAAG,MAAM;EAAW;CAC7E;AACF;AAEA,SAAS,QAAQ,OAAe,MAAc,YAAY,OAAe;CACvE,IAAI,CAAC,OAAO,SAAS,KAAK,KAAK,QAAQ,KAAM,CAAC,aAAa,UAAU,GACnE,MAAM,IAAI,WACR,GAAG,KAAK,+BAA+B,YAAY,gBAAgB,UAAU,EAC/E;CACF,OAAO,KAAK,MAAM,QAAQ,GAAI;AAChC;AAEA,SAAS,cAAc,KAAuB;CAC5C,MAAM,QAAiB,KAAK,MAAM,GAAG;CACrC,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,MAAM,IAAI,UAAU,0BAA0B;CAC/F,MAAM,EAAE,IAAI,UAAU,YAAY;CAClC,IAAI,OAAO,OAAO,YAAY,OAAO,YAAY,YAAY,OAAO,aAAa,UAC/E,MAAM,IAAI,UAAU,0BAA0B;CAChD,OAAO;EAAE;EAAI;EAAU;CAAQ;AACjC"}
|