@pikku/queue-nats 0.12.1

package/dist/nats-service-factory.js

@@ -0,0 +1,231 @@
+import { jetstream, jetstreamManager, RetentionPolicy, } from '@nats-io/jetstream';
+import { connect } from '@nats-io/transport-node';
+import { NatsDelayedPublisher } from './nats-delayed-publisher.js';
+import { NatsQueueService } from './nats-queue-service.js';
+import { NatsSchedulerService } from './nats-scheduler-service.js';
+import { NatsQueueWorkers } from './nats-queue-worker.js';
+/** Server version that first shipped repeating (cron / `@every`) message schedules. */
+const MIN_SCHEDULER_VERSION = [2, 14, 0];
+/**
+ * Refuse to start against a server too old to schedule messages.
+ *
+ * Without this the failure is late, rare and cryptic: the stream config quietly
+ * drops `allow_msg_schedules`, every publish keeps working, and the first thing
+ * anyone notices is that a cron never fired — or a publish is rejected with
+ * `10188 message schedules is disabled`, minutes to hours after boot, on a code
+ * path nobody was watching. Since this package no longer carries a pg-boss
+ * fallback, an old server means scheduling is simply absent, so it is worth
+ * failing at connect time and naming the actual requirement.
+ */
+const assertSchedulerSupport = (version) => {
+    if (!version)
+        return;
+    const parts = version.split('.').map((n) => Number.parseInt(n, 10));
+    if (parts.length < 3 || parts.some(Number.isNaN))
+        return;
+    const [major, minor, patch] = parts;
+    const [reqMajor, reqMinor, reqPatch] = MIN_SCHEDULER_VERSION;
+    const ok = major > reqMajor ||
+        (major === reqMajor &&
+            (minor > reqMinor || (minor === reqMinor && patch >= reqPatch)));
+    if (ok)
+        return;
+    throw new Error(`NATS server ${version} is too old: message schedules (cron and delayed publish) need ` +
+        `${MIN_SCHEDULER_VERSION.join('.')}+. Upgrading is one-way — the stream-state file format ` +
+        `changed in 2.11 and again in 2.12, and there is no documented path back to 2.10 — so back ` +
+        `up the JetStream store directory before upgrading the server.`);
+};
+/**
+ * Factory for the JetStream queue services.
+ *
+ * Mirrors PgBossServiceFactory, including `getSchedulerService`. That was not
+ * always true: this package originally had no scheduler at all, because
+ * JetStream had no delayed or scheduled message primitive and cron therefore
+ * stayed on pg-boss. Server 2.12 added one-shot `@at` delays and 2.14 added
+ * repeating cron schedules, so the split no longer buys anything and the
+ * pg-boss dependency is gone.
+ */
+export class NatsServiceFactory {
+    options;
+    connection;
+    js;
+    jsm;
+    queueService;
+    queueWorkers;
+    schedulerService;
+    initialized = false;
+    /** Set by `close()`, so the close watcher can tell a shutdown from a fault. */
+    closing = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        this.connection = await connect({
+            servers: this.options.servers,
+            user: this.options.user,
+            pass: this.options.pass,
+            token: this.options.token,
+            name: this.options.name,
+            // RECONNECT FOREVER. The client default is 10 attempts, 2s apart, so about
+            // twenty seconds of NATS being unreachable CLOSES the connection for good —
+            // and `init()` runs once at boot, so nothing ever reopens it. The process
+            // then looks healthy (HTTP fine, database fine, reads fine) while every
+            // workflow dispatch throws `ClosedConnectionError` until someone restarts
+            // the backend. That is the shape of the intermittent "project stuck in
+            // creating" wedge: the row is written, the workflow that would build it is
+            // never enqueued, and nothing surfaces because the failure is in a queue
+            // publish rather than the request.
+            //
+            // A NATS restart routinely exceeds that budget, so the default turns
+            // ordinary maintenance into a silent outage that outlives it. There is no
+            // upside to giving up: a queue producer with nowhere to publish has no
+            // useful degraded mode, and retrying forever costs one socket attempt every
+            // few seconds.
+            maxReconnectAttempts: -1,
+            reconnectTimeWait: 2_000,
+            // Spread the herd. Every backend process reconnects off the same outage, and
+            // without jitter they retry in lockstep and hit the server together at the
+            // moment it is least able to take them.
+            reconnectJitter: 1_000,
+            // Boot must not race the queue either: without this, a backend starting
+            // while NATS is still coming up fails `init()` outright rather than waiting
+            // for it, which is the same outage one layer earlier.
+            waitOnFirstConnect: true,
+        });
+        void this.watchForUnexpectedClose(this.connection);
+        assertSchedulerSupport(this.connection.info?.version);
+        const jsm = await jetstreamManager(this.connection);
+        const js = jetstream(this.connection);
+        this.js = js;
+        this.jsm = jsm;
+        // WorkQueue retention: a message is removed from the stream the instant it
+        // is acked. That is what makes this a queue rather than a log, and it is
+        // also why there is no history here — a completed job leaves no trace in
+        // NATS, so success/failure rates must come from telemetry instead.
+        //
+        // WorkQueue also requires consumer filter subjects not to overlap, which is
+        // satisfied by construction: one consumer per queue, filtered to exactly
+        // that queue's subject.
+        const streamConfig = {
+            name: this.options.streamName,
+            subjects: [`${this.options.subjectPrefix}.>`],
+            retention: RetentionPolicy.Workqueue,
+            num_replicas: this.options.replicas ?? 1,
+            // Lets this stream hold schedule messages, which is how delayed publishes
+            // and cron work — see NatsDelayedPublisher. Schedules must live in the
+            // same stream as the subject they target, so this goes on the queue
+            // stream itself rather than a stream beside it.
+            //
+            // Safe to turn on for an existing stream (it applies without recreating),
+            // but note it is one-way: the server has no way to disable it again. It
+            // also implicitly enables AllowRollup and clears DenyPurge, because
+            // schedules are stored as rollup-subject messages.
+            allow_msg_schedules: true,
+            ...(this.options.duplicateWindowMs !== undefined
+                ? { duplicate_window: this.options.duplicateWindowMs * 1_000_000 }
+                : {}),
+        };
+        // `add` is STREAM.CREATE, which errors if the stream exists with a different
+        // config — so the first deploy that changes duplicate_window or replicas
+        // would fail at boot rather than converge. Try create, then update. Update
+        // is the right call for a stream that exists: it applies the new config in
+        // place without touching the messages already in it.
+        try {
+            await jsm.streams.add(streamConfig);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Only "already exists" is recoverable this way; anything else (no
+            // JetStream enabled, bad subject, insufficient replicas for the cluster
+            // size) must surface, not be papered over by a second failing call.
+            if (!/already in use|already exists/i.test(message))
+                throw err;
+            await jsm.streams.update(this.options.streamName, streamConfig);
+        }
+        // Wired at construction rather than via setDelayedPublisher: the pg-boss
+        // publisher had to be attached late because it republished *through* this
+        // service, so the two referenced each other. The native one only needs the
+        // JetStream client, so the cycle is gone.
+        this.queueService = new NatsQueueService(js, this.options.subjectPrefix, new NatsDelayedPublisher(js, this.options.subjectPrefix));
+        this.queueWorkers = new NatsQueueWorkers(js, jsm, this.options.streamName, this.options.subjectPrefix, this.options.defaultConsumerConfig);
+        this.schedulerService = new NatsSchedulerService(js, jsm, this.options.streamName, this.options.subjectPrefix, this.options.schedulerTimezone);
+        this.initialized = true;
+    }
+    /**
+     * Surfaces a connection that closed without being asked to — see
+     * `onConnectionLost`. Detached on purpose: `closed()` resolves only at the end
+     * of the connection's life, so awaiting it would never let `init()` return.
+     */
+    async watchForUnexpectedClose(connection) {
+        const err = await connection.closed();
+        if (this.closing)
+            return;
+        const reason = err instanceof Error ? err : undefined;
+        console.error(`NATS connection closed unexpectedly and will not reopen — this process can no longer publish jobs or run cron. ${reason?.message ?? ''}`);
+        this.options.onConnectionLost?.(reason);
+    }
+    getQueueService() {
+        if (!this.queueService) {
+            throw new Error('NatsServiceFactory.init() must be awaited before use');
+        }
+        return this.queueService;
+    }
+    getSchedulerService() {
+        if (!this.schedulerService) {
+            throw new Error('NatsServiceFactory.init() must be awaited before use');
+        }
+        return this.schedulerService;
+    }
+    getQueueWorkers() {
+        if (!this.queueWorkers) {
+            throw new Error('NatsServiceFactory.init() must be awaited before use');
+        }
+        return this.queueWorkers;
+    }
+    /**
+     * Raw JetStream handles, for callers that run their own consumers instead of
+     * going through pikku's queue registry — see `consumeQueue`.
+     */
+    getJetStream() {
+        if (!this.js || !this.jsm) {
+            throw new Error('NatsServiceFactory.init() must be awaited before use');
+        }
+        return { js: this.js, jsm: this.jsm };
+    }
+    getConnection() {
+        if (!this.connection) {
+            throw new Error('NatsServiceFactory.init() must be awaited before use');
+        }
+        return this.connection;
+    }
+    /** Drain the queue workers, if any are running. Returns the queues that still
+     *  had jobs in flight. Safe before `init()`. */
+    async drainWorkers(timeoutMs) {
+        return (await this.queueWorkers?.drain(timeoutMs)) ?? [];
+    }
+    async close() {
+        // Guarded on the connection rather than on `initialized`, because the two
+        // diverge exactly when it matters: if `init()` fails after `connect()`
+        // resolved — an old server rejected by `assertSchedulerSupport` is the
+        // likely one — `initialized` is still false while a live connection is
+        // already reconnecting forever, and an `initialized` guard would leak it
+        // and keep the process alive.
+        if (!this.connection)
+            return;
+        this.closing = true;
+        await this.schedulerService?.stop();
+        await this.queueWorkers?.stop();
+        // `drain` rather than `close`: it flushes pending acks and lets in-flight
+        // publishes land instead of dropping them, which is the difference between
+        // a clean deploy and a batch of messages redelivered after ack_wait.
+        await this.connection.drain();
+        this.connection = undefined;
+        this.initialized = false;
+    }
+    /** Alias for close() — used by stopSingletonServices. */
+    async stop() {
+        await this.close();
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,122 @@
+import type { JsMsg } from '@nats-io/jetstream';
+import type { QueueJob, QueueJobStatus } from '@pikku/core/queue';
+/** Header carrying the producer's pikku user id through to the worker. */
+export declare const PIKKU_USER_ID_HEADER = "Pikku-User-Id";
+/** Header JetStream itself reads for publish-side dedupe within the stream's window. */
+export declare const NATS_MSG_ID_HEADER = "Nats-Msg-Id";
+/**
+ * Per-job retry policy, carried in headers.
+ *
+ * pg-boss and bullmq store `attempts`/`backoff` per job; JetStream only has
+ * per-consumer `max_deliver` and a plain `nak`. Since the workflow engine sets
+ * these per step — and treats `attempts: 1` as "never retry this" — a
+ * per-consumer setting cannot express it. So the policy rides with the message
+ * and the worker enforces it. Without this a step marked `retries: 0` would be
+ * redelivered forever, because an unset `max_deliver` means unlimited.
+ */
+export declare const ATTEMPTS_HEADER = "Pikku-Attempts";
+export declare const BACKOFF_TYPE_HEADER = "Pikku-Backoff-Type";
+export declare const BACKOFF_DELAY_HEADER = "Pikku-Backoff-Delay";
+/**
+ * Header value for a job's retry limit, rejecting anything the worker could not
+ * enforce.
+ *
+ * `JobOptions.attempts` is typed as a plain number, and an unenforceable value
+ * fails in the worst direction: `attemptsFor` reads a zero, a negative or a NaN
+ * back as "no limit set", and the worker then naks forever. A fraction is worse
+ * than useless — it survives as a number and silently means `ceil(attempts)`.
+ * Both are caller mistakes, so they are refused at enqueue rather than turned
+ * into an infinite redelivery loop nobody asked for.
+ */
+export declare const attemptsHeaderValue: (attempts: number, queueName: string) => string;
+/** Default base delay when a job asks for backoff without naming one. */
+export declare const DEFAULT_BACKOFF_DELAY_MS = 1000;
+/**
+ * Delay before redelivering a message on its `deliveryCount`-th failure.
+ * Exponential mirrors bullmq/pg-boss: base * 2^(n-1), capped so a long-lived
+ * retry cannot drift past any sane ack_wait/visibility reasoning.
+ */
+export declare const backoffDelayMs: (deliveryCount: number, type: string | undefined, baseMs?: number) => number;
+/**
+ * Pikku queue names are free-form strings; NATS subject tokens are not. `.` is
+ * the subject separator and `*`/`>` are wildcards, so a queue name containing
+ * any of them would silently widen a consumer's filter and start stealing other
+ * queues' messages. Replace them rather than rejecting, and keep the mapping
+ * total so the same queue name always resolves to the same subject.
+ *
+ * Not injective, and knowingly so: `a.b` and `a_b` collapse to the same token,
+ * so two queues named that way would share one subject and one durable
+ * consumer. An escaping scheme would fix it, at the cost of changing the
+ * subject and durable name of every queue that already exists — which strands
+ * the backlog on the old names. Not worth it for a collision that needs two
+ * queue names differing only in a separator.
+ */
+export declare const queueNameToToken: (queueName: string) => string;
+/** Subject a job for `queueName` is published to. */
+export declare const subjectForQueue: (prefix: string, queueName: string) => string;
+/**
+ * Headers driving JetStream's message scheduler (server 2.12+ for `@at`, 2.14+
+ * for repeating schedules). The server strips every `Nats-Schedule*` header
+ * from the message it produces, so these never reach a worker.
+ */
+export declare const SCHEDULE_HEADER = "Nats-Schedule";
+export declare const SCHEDULE_TARGET_HEADER = "Nats-Schedule-Target";
+export declare const SCHEDULE_TIMEZONE_HEADER = "Nats-Schedule-Time-Zone";
+/** Set by the server on produced messages: the subject holding the schedule. */
+export declare const SCHEDULER_HEADER = "Nats-Scheduler";
+/** Set by the server on produced messages; also the client's cancel verb (`purge`). */
+export declare const SCHEDULE_NEXT_HEADER = "Nats-Schedule-Next";
+/**
+ * Subject segment reserved for schedule messages.
+ *
+ * A schedule must live in the same stream as the subject it targets, so these
+ * sit inside the queue stream rather than beside it. The segment leads with `_`
+ * so it cannot collide with a queue token: `queueNameToToken` never introduces
+ * a leading underscore, and a queue literally named `_schedule` would collide
+ * with itself long before it reached here.
+ *
+ * Nothing consumes this subject, and that is load-bearing on a WorkQueue
+ * stream: a consumer that acked a schedule message would delete it, and a
+ * deleted schedule stops firing with no error and no advisory.
+ */
+export declare const SCHEDULE_SUBJECT_SEGMENT = "_schedule";
+/**
+ * Subject holding the schedule for a queue.
+ *
+ * Every schedule needs its own subject, because the last message on a subject
+ * *is* the schedule — republishing to the same subject replaces it. For
+ * repeating schedules that is exactly the update semantics we want, so `key`
+ * identifies the schedule. For one-shot delayed publishes there is no such
+ * identity, and reusing a subject would make two concurrent delayed jobs
+ * silently overwrite each other, so an absent key gets a unique suffix.
+ */
+export declare const scheduleSubjectFor: (prefix: string, queueName: string, key?: string) => string;
+/**
+ * Durable consumer name for a queue. NATS rejects `.` in durable names, so both
+ * halves have to be tokenised — the prefix as much as the queue name, since a
+ * hierarchical prefix like `app.dispatch` is perfectly valid as a subject
+ * and would otherwise produce a name the server refuses.
+ */
+export declare const consumerNameForQueue: (prefix: string, queueName: string) => string;
+/**
+ * A JetStream message has no terminal states to report: once it is acked it is
+ * removed from a work-queue stream, and once it is termed it is gone too. So a
+ * message we are holding is always mid-delivery — 'active' is the only status
+ * that can be observed from the message itself. Historical outcomes have to come
+ * from telemetry, not from the broker.
+ */
+export declare const jsMsgStatus: () => QueueJobStatus;
+/** The job's own retry limit, if the producer set one. */
+export declare const attemptsFor: (msg: JsMsg) => number | undefined;
+/** Redelivery delay for this message's next attempt, per its backoff policy. */
+export declare const backoffFor: (msg: JsMsg) => number;
+export declare const jsMsgMetadata: (msg: JsMsg) => {
+    attemptsMade: number;
+    createdAt: Date;
+    processedAt: Date;
+};
+/**
+ * Wrap a JetStream message as a pikku QueueJob. `waitForCompletion` is absent
+ * deliberately — see NatsQueueService.supportsResults.
+ */
+export declare const mapJsMsgToQueueJob: <T, R>(queueName: string, msg: JsMsg) => QueueJob<T, R>;

package/dist/utils.js

@@ -0,0 +1,154 @@
+/** Header carrying the producer's pikku user id through to the worker. */
+export const PIKKU_USER_ID_HEADER = 'Pikku-User-Id';
+/** Header JetStream itself reads for publish-side dedupe within the stream's window. */
+export const NATS_MSG_ID_HEADER = 'Nats-Msg-Id';
+/**
+ * Per-job retry policy, carried in headers.
+ *
+ * pg-boss and bullmq store `attempts`/`backoff` per job; JetStream only has
+ * per-consumer `max_deliver` and a plain `nak`. Since the workflow engine sets
+ * these per step — and treats `attempts: 1` as "never retry this" — a
+ * per-consumer setting cannot express it. So the policy rides with the message
+ * and the worker enforces it. Without this a step marked `retries: 0` would be
+ * redelivered forever, because an unset `max_deliver` means unlimited.
+ */
+export const ATTEMPTS_HEADER = 'Pikku-Attempts';
+export const BACKOFF_TYPE_HEADER = 'Pikku-Backoff-Type';
+export const BACKOFF_DELAY_HEADER = 'Pikku-Backoff-Delay';
+/**
+ * Header value for a job's retry limit, rejecting anything the worker could not
+ * enforce.
+ *
+ * `JobOptions.attempts` is typed as a plain number, and an unenforceable value
+ * fails in the worst direction: `attemptsFor` reads a zero, a negative or a NaN
+ * back as "no limit set", and the worker then naks forever. A fraction is worse
+ * than useless — it survives as a number and silently means `ceil(attempts)`.
+ * Both are caller mistakes, so they are refused at enqueue rather than turned
+ * into an infinite redelivery loop nobody asked for.
+ */
+export const attemptsHeaderValue = (attempts, queueName) => {
+    if (!Number.isSafeInteger(attempts) || attempts < 1) {
+        throw new Error(`Queue "${queueName}" was given attempts=${attempts}, which is not a positive integer. An unenforceable limit reads back as "no limit" and the job would be retried forever; pass attempts >= 1 or omit it.`);
+    }
+    return String(attempts);
+};
+/** Default base delay when a job asks for backoff without naming one. */
+export const DEFAULT_BACKOFF_DELAY_MS = 1_000;
+/**
+ * Delay before redelivering a message on its `deliveryCount`-th failure.
+ * Exponential mirrors bullmq/pg-boss: base * 2^(n-1), capped so a long-lived
+ * retry cannot drift past any sane ack_wait/visibility reasoning.
+ */
+export const backoffDelayMs = (deliveryCount, type, baseMs = DEFAULT_BACKOFF_DELAY_MS) => {
+    if (!type)
+        return 0;
+    if (type === 'fixed')
+        return baseMs;
+    // 'exponential' and anything unrecognised — growing is the safe default,
+    // since the failure mode of guessing wrong is retrying too slowly, not too fast.
+    const capMs = 60 * 60_000;
+    return Math.min(baseMs * 2 ** Math.max(0, deliveryCount - 1), capMs);
+};
+/**
+ * Pikku queue names are free-form strings; NATS subject tokens are not. `.` is
+ * the subject separator and `*`/`>` are wildcards, so a queue name containing
+ * any of them would silently widen a consumer's filter and start stealing other
+ * queues' messages. Replace them rather than rejecting, and keep the mapping
+ * total so the same queue name always resolves to the same subject.
+ *
+ * Not injective, and knowingly so: `a.b` and `a_b` collapse to the same token,
+ * so two queues named that way would share one subject and one durable
+ * consumer. An escaping scheme would fix it, at the cost of changing the
+ * subject and durable name of every queue that already exists — which strands
+ * the backlog on the old names. Not worth it for a collision that needs two
+ * queue names differing only in a separator.
+ */
+export const queueNameToToken = (queueName) => queueName.replace(/[.*>\s]/g, '_');
+/** Subject a job for `queueName` is published to. */
+export const subjectForQueue = (prefix, queueName) => `${prefix}.${queueNameToToken(queueName)}`;
+/**
+ * Headers driving JetStream's message scheduler (server 2.12+ for `@at`, 2.14+
+ * for repeating schedules). The server strips every `Nats-Schedule*` header
+ * from the message it produces, so these never reach a worker.
+ */
+export const SCHEDULE_HEADER = 'Nats-Schedule';
+export const SCHEDULE_TARGET_HEADER = 'Nats-Schedule-Target';
+export const SCHEDULE_TIMEZONE_HEADER = 'Nats-Schedule-Time-Zone';
+/** Set by the server on produced messages: the subject holding the schedule. */
+export const SCHEDULER_HEADER = 'Nats-Scheduler';
+/** Set by the server on produced messages; also the client's cancel verb (`purge`). */
+export const SCHEDULE_NEXT_HEADER = 'Nats-Schedule-Next';
+/**
+ * Subject segment reserved for schedule messages.
+ *
+ * A schedule must live in the same stream as the subject it targets, so these
+ * sit inside the queue stream rather than beside it. The segment leads with `_`
+ * so it cannot collide with a queue token: `queueNameToToken` never introduces
+ * a leading underscore, and a queue literally named `_schedule` would collide
+ * with itself long before it reached here.
+ *
+ * Nothing consumes this subject, and that is load-bearing on a WorkQueue
+ * stream: a consumer that acked a schedule message would delete it, and a
+ * deleted schedule stops firing with no error and no advisory.
+ */
+export const SCHEDULE_SUBJECT_SEGMENT = '_schedule';
+/**
+ * Subject holding the schedule for a queue.
+ *
+ * Every schedule needs its own subject, because the last message on a subject
+ * *is* the schedule — republishing to the same subject replaces it. For
+ * repeating schedules that is exactly the update semantics we want, so `key`
+ * identifies the schedule. For one-shot delayed publishes there is no such
+ * identity, and reusing a subject would make two concurrent delayed jobs
+ * silently overwrite each other, so an absent key gets a unique suffix.
+ */
+export const scheduleSubjectFor = (prefix, queueName, key) => `${prefix}.${SCHEDULE_SUBJECT_SEGMENT}.${queueNameToToken(queueName)}.${key
+    ? queueNameToToken(key)
+    : `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`}`;
+/**
+ * Durable consumer name for a queue. NATS rejects `.` in durable names, so both
+ * halves have to be tokenised — the prefix as much as the queue name, since a
+ * hierarchical prefix like `app.dispatch` is perfectly valid as a subject
+ * and would otherwise produce a name the server refuses.
+ */
+export const consumerNameForQueue = (prefix, queueName) => `${queueNameToToken(prefix)}_${queueNameToToken(queueName)}`;
+/**
+ * A JetStream message has no terminal states to report: once it is acked it is
+ * removed from a work-queue stream, and once it is termed it is gone too. So a
+ * message we are holding is always mid-delivery — 'active' is the only status
+ * that can be observed from the message itself. Historical outcomes have to come
+ * from telemetry, not from the broker.
+ */
+export const jsMsgStatus = () => 'active';
+/** The job's own retry limit, if the producer set one. */
+export const attemptsFor = (msg) => {
+    const raw = msg.headers?.get(ATTEMPTS_HEADER);
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+};
+/** Redelivery delay for this message's next attempt, per its backoff policy. */
+export const backoffFor = (msg) => {
+    const type = msg.headers?.get(BACKOFF_TYPE_HEADER) || undefined;
+    const rawBase = msg.headers?.get(BACKOFF_DELAY_HEADER);
+    const base = rawBase ? Number(rawBase) : undefined;
+    return backoffDelayMs(msg.info.deliveryCount, type, Number.isFinite(base) && base > 0 ? base : DEFAULT_BACKOFF_DELAY_MS);
+};
+export const jsMsgMetadata = (msg) => ({
+    attemptsMade: msg.info.deliveryCount,
+    createdAt: new Date(Number(msg.info.timestampNanos) / 1_000_000),
+    processedAt: new Date(),
+});
+/**
+ * Wrap a JetStream message as a pikku QueueJob. `waitForCompletion` is absent
+ * deliberately — see NatsQueueService.supportsResults.
+ */
+export const mapJsMsgToQueueJob = (queueName, msg) => ({
+    id: String(msg.seq),
+    queueName,
+    status: jsMsgStatus,
+    data: msg.json(),
+    metadata: () => jsMsgMetadata(msg),
+    pikkuUserId: msg.headers?.get(PIKKU_USER_ID_HEADER) || undefined,
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pikku/queue-nats",
+  "version": "0.12.1",
+  "description": "NATS JetStream queue, worker and scheduler services for Pikku",
+  "author": "yasser.fadl@gmail.com",
+  "license": "MIT",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "tsc": "tsc",
+    "test": "bash run-tests.sh",
+    "test:coverage": "bash run-tests.sh --coverage",
+    "ncu": "npx npm-check-updates",
+    "build": "tsc -b",
+    "release": "npm run build && npm test",
+    "prepublishOnly": "yarn build"
+  },
+  "peerDependencies": {
+    "@pikku/core": "^0.12.105"
+  },
+  "dependencies": {
+    "@nats-io/jetstream": "^3.4.0",
+    "@nats-io/nats-core": "^3.4.0",
+    "@nats-io/transport-node": "^3.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  }
+}

package/run-tests.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$script_dir"
+
+# Enable nullglob to handle cases where no files match the pattern
+shopt -s nullglob
+
+# Initialize variables for options
+watch_mode=false
+coverage_mode=false
+
+# Parse command-line options
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --watch)
+      watch_mode=true
+      shift
+      ;;
+    --coverage)
+      coverage_mode=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Define the pattern to match your test files
+pattern="src/*.test.ts"
+
+# Expand the pattern into an array of files
+files=($(find src -type f -name "*.test.ts"))
+
+# Check if any files matched the pattern
+if [ ${#files[@]} -eq 0 ]; then
+  echo "No test files found matching pattern: $pattern"
+  exit 0
+fi
+
+# Construct the node command
+node_cmd=(node --import tsx --test)
+
+# Append options based on flags
+if [ "$watch_mode" = true ]; then
+  node_cmd+=(--watch)
+fi
+
+if [ "$coverage_mode" = true ]; then
+  node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+fi
+
+# Execute the node command with the expanded list of files
+"${node_cmd[@]}" "${files[@]}"