effect-mq 0.6.0 → 0.7.0

package/dist/redis/scripts.d.ts

@@ -21,6 +21,19 @@
  * - `p:delayed:<queue>`         ZSET, score `runAt`
  * - `p:active`                  ZSET, score `lockExpiresAt`
  * - `p:all`                     ZSET, score `enqueuedAt` (list pagination)
+ * - `p:byname:<name>`           ZSET, score `enqueuedAt` (list name index;
+ *                               optional, `RedisJobStoreOptions.indexes.name`)
+ * - `p:byqueue:<queue>`         ZSET, score `enqueuedAt` (list queue index;
+ *                               optional, `RedisJobStoreOptions.indexes.queue`)
+ * - `p:index:<kind>:ready`      STRING, millis timestamp of the last index
+ *                               reconcile's start for `<kind>` (name |
+ *                               queue). Absent: the next enabled boot does a
+ *                               full ZSCAN rebuild. Present: enabled boots
+ *                               heal the tail (rows enqueued since the value
+ *                               minus a safety margin) and re-stamp it —
+ *                               closing the rolling-deploy window where
+ *                               index-less writers inserted rows after the
+ *                               marker landed
  * - `p:finished:<state>`        ZSET, score `finishedAt` (history TTL)
  * - `p:terminal:<name>:<state>` ZSET, score `finishedAt` (keep pruning)
  * - `p:counts`                  HASH `<queue>|<state>` -> integer
@@ -49,6 +62,27 @@
  * @since 0.2.0
  */
 import { Redis } from "effect/unstable/persistence";
+/**
+ * Which optional list indexes (`p:byname:<name>` / `p:byqueue:<queue>`) this
+ * store maintains. The flags are baked into the script text (the helpers are
+ * shared by every script), so a store instance only ever runs scripts that
+ * match its configuration — disabled indexes cost no writes at all.
+ *
+ * @since 0.7.0
+ */
+export interface IndexConfig {
+    readonly name: boolean;
+    readonly queue: boolean;
+}
+/**
+ * Shared helpers textually prepended to every script (the `Redis.script`
+ * runner has no include mechanism). `ARGV[1]` is always the key prefix.
+ * Built once per store instance: `insertJobRow` writes only the list indexes
+ * enabled by `IndexConfig` (`deleteJob` clears both unconditionally — a ZREM
+ * on a missing key is free, and stray entries from an earlier configuration
+ * must never outlive their job).
+ */
+export declare const helpers: (indexes: IndexConfig) => string;
 /**
  * enqueue(prefix, idMode, id, name, queue, payloadJson, metadataJson,
  *         priority, attemptsMax, backoffJson, keepJson, timeoutMs, delayMs,
@@ -56,7 +90,7 @@ import { Redis } from "effect/unstable/persistence";
  * idMode: "user" (dedup no-op), "generated" (collision -> retry sentinel),
  * "auto" (j-<seq>, in-script collision loop).
  */
-export declare const enqueue: Redis.Script<{
+export declare const enqueue: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, idMode: string, id: string, name: string, queue: string, payloadJson: string, metadataJson: string, priority: number, attemptsMax: number, backoffJson: string, keepJson: string, timeoutMs: string, delayMs: number, now: number, dedupeKey: string, dedupeTtlMs: string, dedupeExtend: string, dedupeReplace: string, traceJson: string, parentJson: string];
     result: string;
 }>;
@@ -66,7 +100,7 @@ export declare const enqueue: Redis.Script<{
  * waiting job whose name matches. Returns the claimed record (HGETALL pairs)
  * or an Empty result with the earliest matching delayed runAt.
  */
-export declare const claim: Redis.Script<{
+export declare const claim: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, queue: string, namesJson: string, token: string, lockDurationMs: number, now: number];
     result: string;
 }>;
@@ -75,7 +109,7 @@ export declare const claim: Redis.Script<{
  * Token-guarded. Retry on a cancel-requested job finishes it as cancelled
  * (cancellation wins over revival, mirroring release/recoverStalled).
  */
-export declare const ack: Redis.Script<{
+export declare const ack: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string, token: string, outcomeTag: string, exitJson: string, delayMs: number, now: number];
     result: string;
 }>;
@@ -83,7 +117,7 @@ export declare const ack: Redis.Script<{
  * release(prefix, id, token, now) — hand the job back without consuming an
  * attempt; a pending cancel wins and finishes the job instead.
  */
-export declare const release: Redis.Script<{
+export declare const release: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string, token: string, now: number];
     result: string;
 }>;
@@ -91,7 +125,7 @@ export declare const release: Redis.Script<{
  * extendLocks(prefix, locksJson, durationMs, now) -> { lost, cancel }
  * Cancel-requested locks are reported, not extended.
  */
-export declare const extendLocks: Redis.Script<{
+export declare const extendLocks: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, locksJson: string, durationMs: number, now: number];
     result: string;
 }>;
@@ -99,35 +133,72 @@ export declare const extendLocks: Redis.Script<{
  * recoverStalled(prefix, maxStalledCount, now) -> recovered [{id, failed}]
  * A pending cancel finishes the job as cancelled (not reported as recovered).
  */
-export declare const recoverStalled: Redis.Script<{
+export declare const recoverStalled: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, maxStalledCount: number, now: number];
     result: string;
 }>;
 /** getJob(prefix, id) -> HGETALL pairs (empty array when missing). */
-export declare const getJob: Redis.Script<{
+export declare const getJob: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string];
     result: string;
 }>;
 /**
- * list(prefix, filtersJson, cursor, limit)
- * Keyset pagination over p:all, newest first (enqueuedAt DESC, id DESC).
+ * list(prefix, sourcesJson, order, filtersJson, cursor, limit)
+ *
+ * Indexed list. The DRIVER routes the query to the narrowest zset(s) — see
+ * `RedisJobStore`'s routing matrix — and this script merges those sorted
+ * sources by (score, id) in the requested direction, pages past the
+ * exclusive `<orderValue>:<id>` keyset cursor, loads each candidate row, and
+ * applies the residual predicates until `limit` matches accumulate. Sources
+ * must be plain-id-membered zsets whose score IS the requested order value
+ * (`all`/`byname:`/`byqueue:` = enqueuedAt, `delayed:<queue>` = runAt,
+ * `finished:`/`terminal:` = finishedAt) and must be pairwise disjoint; the
+ * waiting zsets (seq-prefixed members, priority scores) are never routed
+ * here. A member whose job hash is gone is an orphan: it is ZREM'd from the
+ * source being scanned (self-heal) and skipped.
+ */
+export declare const list: (HELPERS: string) => Redis.Script<{
+    params: [prefix: string, sourcesJson: string, order: string, filtersJson: string, cursor: string, limit: number];
+    result: string;
+}>;
+/**
+ * indexMembers(prefix, kind, idsJson) -> "1"
+ *
+ * Index one ZSCAN chunk of `p:all` members during a full rebuild. The driver
+ * owns the ZSCAN cursor loop (linear, tie-immune, guaranteed to terminate,
+ * and guaranteed to return every element present for the whole scan); this
+ * script only does the per-chunk work, so the single-threaded server is
+ * never held for the whole keyspace. Re-visited members and rows indexed
+ * live by insertJobRow mid-scan are idempotent ZADDs.
+ */
+export declare const indexMembers: (HELPERS: string) => Redis.Script<{
+    params: [prefix: string, kind: string, idsJson: string];
+    result: string;
+}>;
+/**
+ * indexTailPage(prefix, kind, min, offset, pageSize) -> scanned count
+ *
+ * One bounded page of the boot-time tail heal: index every `p:all` member
+ * with score >= min (the previous marker minus a safety margin). Plain
+ * LIMIT offset paging — tails are small, and a rank-shift skip from a
+ * concurrent delete is covered by the margin plus the next boot's heal.
  */
-export declare const list: Redis.Script<{
-    params: [prefix: string, filtersJson: string, cursor: string, limit: number];
+export declare const indexTailPage: (HELPERS: string) => Redis.Script<{
+    params: [prefix: string, kind: string, min: string, offset: number, pageSize: number];
     result: string;
 }>;
 /** counts(prefix) -> HGETALL pairs of p:counts. */
-export declare const counts: Redis.Script<{
+export declare const counts: (HELPERS: string) => Redis.Script<{
     params: [prefix: string];
     result: string;
 }>;
 /** remove(prefix, id) -> removed boolean (active/waiting-children refused). */
-export declare const remove: Redis.Script<{
+export declare const remove: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string];
     result: string;
 }>;
 /** retry(prefix, id, now) — failed -> waiting with a fresh budget. */
-export declare const retry: Redis.Script<{
+export declare const retry: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string, now: number];
     result: string;
 }>;
@@ -137,12 +208,12 @@ export declare const retry: Redis.Script<{
  * handing them to the cascade sweep); active gets the cancel-request flag;
  * terminal states are refused.
  */
-export declare const cancel: Redis.Script<{
+export declare const cancel: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string, now: number];
     result: string;
 }>;
 /** promote(prefix, id, now) — delayed -> waiting now. */
-export declare const promote: Redis.Script<{
+export declare const promote: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string, now: number];
     result: string;
 }>;
@@ -155,27 +226,27 @@ export declare const promote: Redis.Script<{
  * digits) and empty arrays ({}). An unchanged cadence (cron/tz/everyMs)
  * preserves the stored nextRunAt.
  */
-export declare const upsertSchedule: Redis.Script<{
+export declare const upsertSchedule: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, key: string, jobName: string, queue: string, cron: string, tz: string, everyMs: string, payloadJson: string, metadataJson: string, priority: string, attemptsMax: string, backoffJson: string, keepJson: string, timeoutMs: string, group: string, nextRunAt: number];
     result: string;
 }>;
 /** removeSchedule(prefix, key) -> existed boolean. */
-export declare const removeSchedule: Redis.Script<{
+export declare const removeSchedule: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, key: string];
     result: string;
 }>;
 /** listSchedules(prefix, filtersJson) ordered by nextRunAt ascending. */
-export declare const listSchedules: Redis.Script<{
+export declare const listSchedules: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, filtersJson: string];
     result: string;
 }>;
 /** dueSchedules(prefix, now) ordered by nextRunAt ascending. */
-export declare const dueSchedules: Redis.Script<{
+export declare const dueSchedules: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, now: number];
     result: string;
 }>;
 /** advanceSchedule(prefix, key, expectedRunAt, nextRunAt) — conditional CAS. */
-export declare const advanceSchedule: Redis.Script<{
+export declare const advanceSchedule: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, key: string, expectedRunAt: number, nextRunAt: number];
     result: string;
 }>;
@@ -187,7 +258,7 @@ export declare const advanceSchedule: Redis.Script<{
  * in one script, so a stale sweeper can never re-fire a slot — even after
  * retention pruned the previous slot's job row.
  */
-export declare const tickSchedule: Redis.Script<{
+export declare const tickSchedule: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, key: string, expectedRunAt: number, nextRunAt: number, id: string, name: string, queue: string, payloadJson: string, metadataJson: string, priority: number, attemptsMax: number, backoffJson: string, keepJson: string, timeoutMs: string, traceJson: string, parentJson: string, delayMs: number, now: number];
     result: string;
 }>;
@@ -198,7 +269,7 @@ export declare const tickSchedule: Redis.Script<{
  * backoffJson, keepJson, timeoutMs, traceJson, parentJson, delayMs. Plain
  * (non-dedup) items only — the caller routes dedup items through \`enqueue\`.
  */
-export declare const enqueueMany: Redis.Script<{
+export declare const enqueueMany: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, now: number, count: number, items: readonly string[]];
     result: string;
 }>;
@@ -208,7 +279,7 @@ export declare const enqueueMany: Redis.Script<{
  * min(store ceiling, per-row keep.age). The caller advances the offset by
  * (scanned - deleted) and stops when a page comes back short.
  */
-export declare const sweepState: Redis.Script<{
+export declare const sweepState: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, state: string, ttlMs: string, limit: number, offset: number, now: number];
     result: string;
 }>;
@@ -217,7 +288,7 @@ export declare const sweepState: Redis.Script<{
  * caller loops until 0): expired windows, then pending pointers (+inf)
  * whose job is gone or terminal.
  */
-export declare const sweepDedupes: Redis.Script<{
+export declare const sweepDedupes: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, limit: number, now: number];
     result: string;
 }>;
@@ -240,7 +311,7 @@ export declare const sweepDedupes: Redis.Script<{
  * raced cancelRequested wins: the parent settles cancelled and its pending
  * rows flip to cancelled (cascade work for the flow sweeper).
  */
-export declare const fanOut: Redis.Script<{
+export declare const fanOut: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, id: string, token: string, final: string, clearStaged: string, failFast: string, total: number, now: number, count: number, items: readonly string[]];
     result: string;
 }>;
@@ -261,7 +332,7 @@ export declare const fanOut: Redis.Script<{
  * transition, so its own report goes to the outbox here), else pending==0
  * resumes the parent runnable at the flow's LAST applied report's index.
  */
-export declare const recordChildResults: Redis.Script<{
+export declare const recordChildResults: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, now: number, count: number, items: readonly string[]];
     result: string;
 }>;
@@ -271,7 +342,7 @@ export declare const recordChildResults: Redis.Script<{
  * Items are positional HMGET tuples (the field list must stay in lockstep
  * with the driver's `toChildRecord`) — the full spec JSON stays server-side.
  */
-export declare const listChildResults: Redis.Script<{
+export declare const listChildResults: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, flowId: string, cursor: string, limit: number];
     result: string;
 }>;
@@ -296,7 +367,7 @@ export declare const listChildResults: Redis.Script<{
  * Spec JSON strings pass through untouched — the script never cjson-decodes
  * stored payloads (precision, lone surrogates).
  */
-export declare const flowSweepWork: Redis.Script<{
+export declare const flowSweepWork: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, pendingAgeMs: number, limit: number, now: number];
     result: string;
 }>;
@@ -304,7 +375,7 @@ export declare const flowSweepWork: Redis.Script<{
  * markChildrenCascaded(prefix, flowId, childKeysJson) — idempotent; unknown
  * keys are ignored (their index members are still cleared).
  */
-export declare const markChildrenCascaded: Redis.Script<{
+export declare const markChildrenCascaded: (HELPERS: string) => Redis.Script<{
     params: [prefix: string, flowId: string, childKeysJson: string];
     result: string;
 }>;

package/dist/redis/scripts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/redis/scripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAA;AAkPnD;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;EAkIM,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;EAsEQ,CAAA;AAE1B;;;;GAIG;AACH,eAAO,MAAM,GAAG;;;EA0EU,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,OAAO;;;EA4BM,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,WAAW;;;EAuBE,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,cAAc;;;EAiDD,CAAA;AAE1B,sEAAsE;AACtE,eAAO,MAAM,MAAM;;;EAUO,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,IAAI;;;EAsES,CAAA;AAE1B,mDAAmD;AACnD,eAAO,MAAM,MAAM;;;EAUO,CAAA;AAE1B,+EAA+E;AAC/E,eAAO,MAAM,MAAM;;;EAeO,CAAA;AAE1B,sEAAsE;AACtE,eAAO,MAAM,KAAK;;;EA2BQ,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;EAqCO,CAAA;AAE1B,yDAAyD;AACzD,eAAO,MAAM,OAAO;;;EAqBM,CAAA;AAE1B;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;EA8DD,CAAA;AAE1B,sDAAsD;AACtD,eAAO,MAAM,cAAc;;;EAUD,CAAA;AAE1B,yEAAyE;AACzE,eAAO,MAAM,aAAa;;;EAsBA,CAAA;AAE1B,gEAAgE;AAChE,eAAO,MAAM,YAAY;;;EAcC,CAAA;AAE1B,gFAAgF;AAChF,eAAO,MAAM,eAAe;;;EAcF,CAAA;AAE1B;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;EA0DC,CAAA;AAE1B;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;EA+CE,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;EA4DG,CAAA;AAE1B;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;EAyCC,CAAA;AAE1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,MAAM;;;EA+FO,CAAA;AAE1B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB;;;EAmGL,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;EAkBH,CAAA;AAE1B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa;;;EA0EA,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;EAgBP,CAAA"}
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/redis/scripts.ts"],"names":[],"mappings":"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"}