effect-mq 0.1.0 → 0.3.0

package/dist/JobStore.js

@@ -16,7 +16,7 @@
  *
  * @since 0.1.0
  */
-import { Brand, Context, Data, Predicate } from "effect";
+import { Brand, Context, Cron, Data, Duration, Predicate, Result } from "effect";
 /**
  * Brand a raw string as a `JobId`.
  *
@@ -29,6 +29,38 @@ export const JobId = Brand.nominal();
  * @since 0.1.0
  */
 export const QueueName = Brand.nominal();
+/**
+ * Brand a raw string as a `ScheduleKey`.
+ *
+ * @since 0.2.0
+ */
+export const ScheduleKey = Brand.nominal();
+/**
+ * Normalize a `HistoryTtlInput` to milliseconds per terminal state.
+ *
+ * @internal
+ */
+export const normalizeHistoryTtl = (input) => {
+    if (Predicate.isObject(input) && !Duration.isDuration(input)) {
+        if (!("completed" in input || "failed" in input || "cancelled" in input)) {
+            // {} or a DurationObject would silently normalize to a 0ms ceiling and
+            // wipe all history — refuse loudly; use "90 days"-style inputs.
+            throw new Error("effect-mq: historyTtl object must set at least one of completed/failed/cancelled");
+        }
+        // SAFETY: Duration inputs (numbers, strings, bigints, tuples, Duration
+        // instances, DurationObjects) never carry terminal-state keys, so this
+        // is the per-state split form.
+        const split = input;
+        return {
+            completed: split.completed !== undefined ? Duration.toMillis(split.completed) : undefined,
+            failed: split.failed !== undefined ? Duration.toMillis(split.failed) : undefined,
+            cancelled: split.cancelled !== undefined ? Duration.toMillis(split.cancelled) : undefined
+        };
+    }
+    // SAFETY: not the split form (checked above), so a plain Duration input.
+    const ms = Duration.toMillis(input);
+    return { completed: ms, failed: ms, cancelled: ms };
+};
 /**
  * A transient or fatal driver error (connection loss, serialization, etc.).
  *
@@ -43,6 +75,67 @@ export class JobStoreError extends Data.TaggedError("JobStoreError") {
  */
 // oxlint-disable-next-line anti-slop/no-unknown-parameters -- a type guard IS the boundary parser; `unknown` input is its purpose
 export const isJobStoreError = (u) => Predicate.hasProperty(u, "_tag") && u._tag === "JobStoreError";
+// Identity-based marking (WeakSet, works on frozen error instances) so the
+// error keeps its declared type and schema round-trip untouched.
+const unrecoverableRegistry = new WeakSet();
+/**
+ * Mark an error value as unrecoverable: when a handler fails with it, the
+ * worker skips the remaining retry budget and fails the job immediately. The
+ * error itself is returned unchanged, so typed error channels and schemas
+ * are unaffected. Also exported as `Job.unrecoverable`.
+ *
+ * Marking is identity-based, so it only works for object errors — a
+ * primitive (string/number) failure is returned unmarked and retries
+ * normally; use the definition-level `retryable` predicate for those.
+ *
+ * @since 0.2.0
+ */
+export const unrecoverable = (error) => {
+    if (Object(error) === error) {
+        // SAFETY: `Object(x) === x` is true exactly for object values, which is
+        // what WeakSet membership requires.
+        unrecoverableRegistry.add(error);
+    }
+    return error;
+};
+/**
+ * Whether `unrecoverable` marked this value.
+ *
+ * @internal
+ */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- boundary classifier over arbitrary error values
+export const isMarkedUnrecoverable = (u) => 
+// SAFETY: `Object(u) === u` short-circuits to false for primitives, so the
+// assertion only ever passes object values to the WeakSet.
+Object(u) === u && unrecoverableRegistry.has(u);
+/**
+ * The next occurrence of a schedule strictly after `now`. `fromSlot` anchors
+ * `everyMs` schedules (occurrences stay on the `slot + k * every` grid).
+ * Returns undefined for an invalid cron expression.
+ *
+ * @internal
+ */
+export const nextOccurrence = (schedule, fromSlot, now) => {
+    if (schedule.cron !== undefined) {
+        const parsed = Cron.parse(schedule.cron, schedule.tz);
+        if (Result.isFailure(parsed))
+            return undefined;
+        // Cron.next throws for parseable-but-unsatisfiable expressions (e.g.
+        // "0 0 30 2 *"); treat those as invalid rather than defecting the sweep.
+        try {
+            return Cron.next(parsed.success, new Date(Math.max(fromSlot, now))).getTime();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (schedule.everyMs !== undefined && schedule.everyMs > 0) {
+        const behind = Math.max(0, now - fromSlot);
+        const steps = Math.floor(behind / schedule.everyMs) + 1;
+        return fromSlot + steps * schedule.everyMs;
+    }
+    return undefined;
+};
 /**
  * The presented lock token no longer owns the job (it stalled and was
  * recovered, or another worker claimed it).
@@ -63,6 +156,27 @@ export class JobNotFoundError extends Data.TaggedError("JobNotFoundError") {
  */
 export class JobNotRetryableError extends Data.TaggedError("JobNotRetryableError") {
 }
+/**
+ * `cancel` was called on a job that is already terminal.
+ *
+ * @since 0.2.0
+ */
+export class JobNotCancellableError extends Data.TaggedError("JobNotCancellableError") {
+}
+/**
+ * `promote` was called on a job that is not in the `delayed` state.
+ *
+ * @since 0.2.0
+ */
+export class JobNotPromotableError extends Data.TaggedError("JobNotPromotableError") {
+}
+/**
+ * Raised (as a defect) by `awaitResult` when the awaited job was cancelled.
+ *
+ * @since 0.2.0
+ */
+export class JobCancelledError extends Data.TaggedError("JobCancelledError") {
+}
 /**
  * The default store key. Jobs without an explicit `store` binding use this.
  *

package/dist/JobStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"JobStore.js","sourceRoot":"","sources":["../src/JobStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAA4B,SAAS,EAAE,MAAM,QAAQ,CAAA;AAUlF;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAA6B,KAAK,CAAC,OAAO,EAAS,CAAA;AASrE;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAiC,KAAK,CAAC,OAAO,EAAa,CAAA;AAoMjF;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,IAAI,CAAC,WAAW,CAAC,eAAe,CAGjE;CAAG;AAEL;;;;GAIG;AACH,kIAAkI;AAClI,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAsB,EAAE,CAChE,SAAS,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,eAAe,CAAA;AAGhE;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,IAAI,CAAC,WAAW,CAAC,eAAe,CAEjE;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAEvE;CAAG;AAEL;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAG/E;CAAG;AAiHL;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,OAAO,CAAC,OAAO,EAAqB,CAChE,oBAAoB,CACrB;CAAG;AAYJ;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,IAAU,EACyB,EAAE,CACrC,OAAO,CAAC,OAAO,CAAuB,sBAAsB,IAAI,EAAE,CAAC,CAAA"}
+{"version":3,"file":"JobStore.js","sourceRoot":"","sources":["../src/JobStore.ts"],"names":[],"mappings":"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"}

package/dist/MemoryJobStore.d.ts

@@ -10,25 +10,57 @@
  *
  * @since 0.1.0
  */
-import { type Context, Effect, Layer } from "effect";
-import { JobStore, type Service } from "./JobStore.ts";
+import { type Context, Duration, Effect, Layer, type Scope } from "effect";
+import { type HistoryTtlInput, type IdGenerator, JobStore, type Service } from "./JobStore.ts";
 /**
- * Build a fresh in-memory `JobStore` implementation.
+ * @since 0.2.0
+ */
+export interface MemoryJobStoreOptions {
+    /**
+     * Store-level retention ceiling: terminal records older than this are
+     * removed by a periodic sweep — one duration for all terminal states or a
+     * per-state split (`{ completed: "1 day", failed: "30 days" }`). The sweep
+     * also honours stricter per-job `keep.age` rules.
+     */
+    readonly historyTtl?: HistoryTtlInput | undefined;
+    /** Sweep cadence (default 1 minute). */
+    readonly historySweepInterval?: Duration.Input | undefined;
+    /**
+     * Generator for store-assigned job ids (e.g. `() => \`job_${ulid()}\``).
+     * Default: a `j-<n>` counter. See `JobStore.IdGenerator`.
+     */
+    readonly idGenerator?: IdGenerator | undefined;
+}
+/**
+ * Build a fresh in-memory `JobStore` implementation (no history sweeper —
+ * use `makeWith` for `historyTtl` support).
  *
  * @since 0.1.0
  */
 export declare const make: Effect.Effect<Service>;
 /**
- * A fresh in-memory `JobStore` layer. Pass a named store key to provide a
- * `JobStore.named(...)` slot instead of the default.
+ * Build a fresh in-memory `JobStore` with options; the history sweeper (when
+ * configured) lives in the surrounding `Scope`.
+ *
+ * @since 0.2.0
+ */
+export declare const makeWith: (options?: MemoryJobStoreOptions | undefined) => Effect.Effect<Service, never, Scope.Scope>;
+/**
+ * A fresh in-memory `JobStore` layer.
  *
  * @since 0.1.0
  */
 export declare const layer: Layer.Layer<JobStore>;
+/**
+ * An in-memory layer with options (e.g. `historyTtl`).
+ *
+ * @since 0.2.0
+ */
+export declare const layerWith: (options?: MemoryJobStoreOptions | undefined) => Layer.Layer<JobStore>;
 /**
  * An in-memory layer for a specific store key.
  *
  * @since 0.1.0
  */
-export declare const layerFor: <Id>(store: Context.Key<Id, Service>) => Layer.Layer<Id>;
+export declare const layerFor: <Id>(store: Context.Key<Id, Service>, options?: MemoryJobStoreOptions | undefined) => Layer.Layer<Id>;
 //# sourceMappingURL=MemoryJobStore.d.ts.map

package/dist/MemoryJobStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryJobStore.d.ts","sourceRoot":"","sources":["../src/MemoryJobStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAS,KAAK,OAAO,EAAY,MAAM,EAAQ,KAAK,EAAU,MAAM,QAAQ,CAAA;AACnF,OAAO,EASL,QAAQ,EAIR,KAAK,OAAO,EACb,MAAM,eAAe,CAAA;AA0DtB;;;;GAIG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAuWtC,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAgC,CAAA;AAExE;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAClB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,KAC9B,KAAK,CAAC,KAAK,CAAC,EAAE,CAA8B,CAAA"}
+{"version":3,"file":"MemoryJobStore.d.ts","sourceRoot":"","sources":["../src/MemoryJobStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAS,KAAK,OAAO,EAAY,QAAQ,EAAE,MAAM,EAAQ,KAAK,EAAU,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAA;AACzG,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,WAAW,EAShB,QAAQ,EASR,KAAK,OAAO,EACb,MAAM,eAAe,CAAA;AAmuBtB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACjD,wCAAwC;IACxC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IAC1D;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAC/C;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAgD,CAAA;AAExF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,aACT,qBAAqB,GAAG,SAAS,KAC1C,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAaxC,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAsC,CAAA;AAE9E;;;;GAIG;AACH,eAAO,MAAM,SAAS,aACV,qBAAqB,GAAG,SAAS,KAC1C,KAAK,CAAC,KAAK,CAAC,QAAQ,CAA8C,CAAA;AAErE;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAClB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,YACrB,qBAAqB,GAAG,SAAS,KAC1C,KAAK,CAAC,KAAK,CAAC,EAAE,CAA2C,CAAA"}