@vouchington/worker-runtime 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @vouchington/worker-runtime
+
+Generic queue selection, [GlideMQ](https://www.npmjs.com/package/glide-mq) worker loading, and
+schedule registration. It accepts an application-owned list of worker and schedule definitions;
+the package does not name queues, choose deployment topology, or define queue-placement policy.
+
+## Install
+
+```sh
+pnpm add @vouchington/worker-runtime glide-mq
+```
+
+GlideMQ is a peer dependency so loaded workers share the application's GlideMQ instance.
+
+## Queue selection and workers
+
+`parseQueueSelection` reads a comma-separated `QUEUES` value. A blank value selects every queue;
+an all-positive list includes only those names, and an all-negative list excludes those names.
+Mixed signs and empty entries are invalid. Includes are strict by default, while callers handling
+deployment skew can opt into dropping and observing unknown include names.
+
+```ts
+import { loadWorkers, type WorkerDefinition } from '@vouchington/worker-runtime'
+
+const definitions: WorkerDefinition[] = [
+  {
+    queueName: 'send-email',
+    load: () => import('./email-worker.mjs').then((module) => module.worker),
+  },
+]
+
+const workers = await loadWorkers(definitions, process.env.QUEUES)
+```
+
+Definitions marked `requiresExplicitInclusion` run only when an include list names them. Pass
+`queueNamesOwnedByOtherRuntimes` when the same `QUEUES` value also selects queues consumed by a
+sibling runtime; those names are recognized but never loaded by these definitions.
+
+## Schedules
+
+`upsertSchedules` loads and runs schedules for selected queues. A definition may set `alwaysRun`
+when an application intentionally needs it to bypass selection; which schedules may do that is an
+application policy, not a package rule.
+
+## Application-owned concerns
+
+This package deliberately does not implement SQS polling, process lifecycle or shutdown,
+observability, warmups, worker inventories, or queue placement. Cloudflare routing and CSP also
+remain application-owned: they encode each application's routes, origins, authentication, cache,
+and security policy.

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export * from './queue-selection.mts';
+export * from './schedules.mts';
+export * from './workers.mts';

package/dist/index.mjs

@@ -0,0 +1,3 @@
+export * from './queue-selection.mjs';
+export * from './schedules.mjs';
+export * from './workers.mjs';

package/dist/queue-selection.d.mts

@@ -0,0 +1,17 @@
+export type QueueSelection = {
+    mode: 'all';
+    queueNames: ReadonlySet<string>;
+} | {
+    mode: 'include';
+    queueNames: ReadonlySet<string>;
+} | {
+    mode: 'exclude';
+    queueNames: ReadonlySet<string>;
+};
+export interface QueueSelectionOptions {
+    dropUnknownIncludes?: boolean;
+    /** Called with dropped include-mode queue names when tolerant selection is enabled. */
+    onUnknownIncludes?: (unknownQueueNames: readonly string[]) => void;
+}
+export declare function parseQueueSelection(value: string | undefined, knownQueueNames: readonly string[], { dropUnknownIncludes, onUnknownIncludes }?: QueueSelectionOptions): QueueSelection;
+export declare function isQueueSelected(selection: QueueSelection, queueName: string): boolean;

package/dist/queue-selection.mjs

@@ -0,0 +1,41 @@
+export function parseQueueSelection(value, knownQueueNames, { dropUnknownIncludes = false, onUnknownIncludes } = {}) {
+    const known = new Set(knownQueueNames);
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return { mode: 'all', queueNames: new Set() };
+    const parts = trimmed.split(',').map((part) => part.trim());
+    if (parts.some((part) => part.length === 0)) {
+        throw new Error('QUEUES must be a comma-separated list without empty entries');
+    }
+    const excludes = parts.map((part) => part.startsWith('-'));
+    const isExclude = excludes.every(Boolean);
+    if (!isExclude && !excludes.every((exclude) => !exclude)) {
+        throw new Error('QUEUES must use either all include entries or all exclude entries, not both');
+    }
+    const parsedNames = parts.map((part) => (isExclude ? part.slice(1) : part));
+    if (parsedNames.includes('')) {
+        throw new Error('QUEUES exclude entries must include a queue name after "-"');
+    }
+    const unknown = parsedNames.filter((queueName) => !known.has(queueName));
+    if (!isExclude && !dropUnknownIncludes && unknown.length > 0) {
+        throw new Error(`QUEUES contains unknown queue name(s): ${unknown.join(', ')}`);
+    }
+    if (!isExclude && dropUnknownIncludes && unknown.length > 0)
+        onUnknownIncludes?.(unknown);
+    return {
+        mode: isExclude ? 'exclude' : 'include',
+        queueNames: new Set(isExclude || dropUnknownIncludes
+            ? parsedNames.filter((name) => known.has(name))
+            : parsedNames),
+    };
+}
+export function isQueueSelected(selection, queueName) {
+    switch (selection.mode) {
+        case 'all':
+            return true;
+        case 'include':
+            return selection.queueNames.has(queueName);
+        case 'exclude':
+            return !selection.queueNames.has(queueName);
+    }
+}

package/dist/schedules.d.mts

@@ -0,0 +1,7 @@
+export interface ScheduleDefinition {
+    queueName: string;
+    load: () => Promise<() => Promise<void>>;
+    /** Register this schedule even when queue selection excludes it. */
+    alwaysRun?: boolean;
+}
+export declare function upsertSchedules(definitions: readonly ScheduleDefinition[], queues?: string | undefined): Promise<void>;

package/dist/schedules.mjs

@@ -0,0 +1,10 @@
+import { isQueueSelected, parseQueueSelection } from './queue-selection.mjs';
+export async function upsertSchedules(definitions, queues = process.env.QUEUES) {
+    const selection = parseQueueSelection(queues, definitions.map((definition) => definition.queueName), { dropUnknownIncludes: true });
+    await Promise.all(definitions
+        .filter((definition) => definition.alwaysRun || isQueueSelected(selection, definition.queueName))
+        .map(async (definition) => {
+        const upsert = await definition.load();
+        await upsert();
+    }));
+}

package/dist/workers.d.mts

@@ -0,0 +1,9 @@
+import type { Worker } from 'glide-mq';
+export interface WorkerDefinition {
+    queueName: string;
+    load: () => Promise<Worker>;
+    requiresExplicitInclusion?: boolean;
+}
+export type UnknownQueueReporter = (unknownQueueNames: readonly string[]) => void;
+export declare function selectedWorkerDefinitions(definitions: readonly WorkerDefinition[], queues?: string | undefined, onUnknownIncludes?: UnknownQueueReporter, queueNamesOwnedByOtherRuntimes?: readonly string[]): WorkerDefinition[];
+export declare function loadWorkers(definitions: readonly WorkerDefinition[], queues?: string | undefined, onUnknownIncludes?: UnknownQueueReporter, queueNamesOwnedByOtherRuntimes?: readonly string[]): Promise<Worker[]>;

package/dist/workers.mjs

@@ -0,0 +1,19 @@
+import { isQueueSelected, parseQueueSelection } from './queue-selection.mjs';
+export function selectedWorkerDefinitions(definitions, queues = process.env.QUEUES, onUnknownIncludes = () => undefined, queueNamesOwnedByOtherRuntimes = []) {
+    const knownQueueNames = [
+        ...definitions.map((definition) => definition.queueName),
+        ...queueNamesOwnedByOtherRuntimes,
+    ];
+    const selection = parseQueueSelection(queues, knownQueueNames, {
+        dropUnknownIncludes: true,
+        onUnknownIncludes,
+    });
+    return definitions.filter((definition) => {
+        if (definition.requiresExplicitInclusion && selection.mode !== 'include')
+            return false;
+        return isQueueSelected(selection, definition.queueName);
+    });
+}
+export function loadWorkers(definitions, queues = process.env.QUEUES, onUnknownIncludes = () => undefined, queueNamesOwnedByOtherRuntimes = []) {
+    return Promise.all(selectedWorkerDefinitions(definitions, queues, onUnknownIncludes, queueNamesOwnedByOtherRuntimes).map((definition) => definition.load()));
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vouchington/worker-runtime",
+  "version": "0.0.0",
+  "description": "Queue selection, GlideMQ worker loading, and schedule registration.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/worker-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/worker-runtime"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "devDependencies": {
+    "glide-mq": "^0.15.3"
+  },
+  "peerDependencies": {
+    "glide-mq": "^0.15.3"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}