@constructive-io/job-utils 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 0.5.0 (2025-12-18)
+
+### Features
+
+- rebrand PGPM packages from @launchql/_ to @pgpmjs/_ ([734d865](https://github.com/constructive-io/jobs/commit/734d8655ced175f51567c513ac1ee4c843df98b7))
+
+## [0.4.3](https://github.com/constructive-io/jobs/compare/@launchql/job-utils@0.4.2...@launchql/job-utils@0.4.3) (2025-12-17)
+
+**Note:** Version bump only for package @launchql/job-utils

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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 @@
+# job-utils

package/dist/env.d.ts

@@ -0,0 +1,6 @@
+declare const _default: Readonly<{
+    JOBS_SCHEMA: string;
+}> & import("envalid").CleanEnv & {
+    readonly [varName: string]: string;
+};
+export default _default;

package/dist/env.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const envalid_1 = require("envalid");
+exports.default = (0, envalid_1.cleanEnv)(process.env, {
+    JOBS_SCHEMA: (0, envalid_1.str)({ default: 'app_jobs' })
+}, { dotEnvPath: null });

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { FailJobParams, CompleteJobParams, GetJobParams, GetScheduledJobParams, RunScheduledJobParams, ReleaseScheduledJobsParams, ReleaseJobsParams } from '@pgpmjs/types';
+import { getJobSchema, getJobPgConfig, getJobPool, getJobConnectionString, getJobSupportAny, getJobSupported, getWorkerHostname, getSchedulerHostname, getJobGatewayConfig, getJobGatewayDevMap, getJobsCallbackPort, getCallbackBaseUrl, getNodeEnvironment } from './runtime';
+export type PgClientLike = {
+    query<T = any>(text: string, params?: any[]): Promise<{
+        rows: T[];
+    }>;
+};
+export { getJobSchema, getJobPgConfig, getJobPool, getJobConnectionString, getJobSupportAny, getJobSupported, getWorkerHostname, getSchedulerHostname, getJobGatewayConfig, getJobGatewayDevMap, getJobsCallbackPort, getCallbackBaseUrl, getNodeEnvironment };
+export declare const failJob: (client: PgClientLike, { workerId, jobId, message }: FailJobParams) => Promise<void>;
+export declare const completeJob: (client: PgClientLike, { workerId, jobId }: CompleteJobParams) => Promise<void>;
+export declare const getJob: <T = any>(client: PgClientLike, { workerId, supportedTaskNames }: GetJobParams) => Promise<T | null>;
+export declare const getScheduledJob: <T = any>(client: PgClientLike, { workerId, supportedTaskNames }: GetScheduledJobParams) => Promise<T | null>;
+export declare const runScheduledJob: (client: PgClientLike, { jobId }: RunScheduledJobParams) => Promise<any | null>;
+export declare const releaseScheduledJobs: (client: PgClientLike, { workerId, ids }: ReleaseScheduledJobsParams) => Promise<{
+    rows: any[];
+}>;
+export declare const releaseJobs: (client: PgClientLike, { workerId }: ReleaseJobsParams) => Promise<{
+    rows: any[];
+}>;

package/dist/index.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.releaseJobs = exports.releaseScheduledJobs = exports.runScheduledJob = exports.getScheduledJob = exports.getJob = exports.completeJob = exports.failJob = exports.getNodeEnvironment = exports.getCallbackBaseUrl = exports.getJobsCallbackPort = exports.getJobGatewayDevMap = exports.getJobGatewayConfig = exports.getSchedulerHostname = exports.getWorkerHostname = exports.getJobSupported = exports.getJobSupportAny = exports.getJobConnectionString = exports.getJobPool = exports.getJobPgConfig = exports.getJobSchema = void 0;
+const runtime_1 = require("./runtime");
+Object.defineProperty(exports, "getJobSchema", { enumerable: true, get: function () { return runtime_1.getJobSchema; } });
+Object.defineProperty(exports, "getJobPgConfig", { enumerable: true, get: function () { return runtime_1.getJobPgConfig; } });
+Object.defineProperty(exports, "getJobPool", { enumerable: true, get: function () { return runtime_1.getJobPool; } });
+Object.defineProperty(exports, "getJobConnectionString", { enumerable: true, get: function () { return runtime_1.getJobConnectionString; } });
+Object.defineProperty(exports, "getJobSupportAny", { enumerable: true, get: function () { return runtime_1.getJobSupportAny; } });
+Object.defineProperty(exports, "getJobSupported", { enumerable: true, get: function () { return runtime_1.getJobSupported; } });
+Object.defineProperty(exports, "getWorkerHostname", { enumerable: true, get: function () { return runtime_1.getWorkerHostname; } });
+Object.defineProperty(exports, "getSchedulerHostname", { enumerable: true, get: function () { return runtime_1.getSchedulerHostname; } });
+Object.defineProperty(exports, "getJobGatewayConfig", { enumerable: true, get: function () { return runtime_1.getJobGatewayConfig; } });
+Object.defineProperty(exports, "getJobGatewayDevMap", { enumerable: true, get: function () { return runtime_1.getJobGatewayDevMap; } });
+Object.defineProperty(exports, "getJobsCallbackPort", { enumerable: true, get: function () { return runtime_1.getJobsCallbackPort; } });
+Object.defineProperty(exports, "getCallbackBaseUrl", { enumerable: true, get: function () { return runtime_1.getCallbackBaseUrl; } });
+Object.defineProperty(exports, "getNodeEnvironment", { enumerable: true, get: function () { return runtime_1.getNodeEnvironment; } });
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('jobs:core');
+const JOBS_SCHEMA = (0, runtime_1.getJobSchema)();
+const failJob = async (client, { workerId, jobId, message }) => {
+    log.warn(`failJob worker[${workerId}] job[${jobId}] ${message}`);
+    await client.query(`SELECT * FROM "${JOBS_SCHEMA}".fail_job($1, $2, $3);`, [workerId, jobId, message]);
+};
+exports.failJob = failJob;
+const completeJob = async (client, { workerId, jobId }) => {
+    log.info(`completeJob worker[${workerId}] job[${jobId}]`);
+    await client.query(`SELECT * FROM "${JOBS_SCHEMA}".complete_job($1, $2);`, [workerId, jobId]);
+};
+exports.completeJob = completeJob;
+const getJob = async (client, { workerId, supportedTaskNames }) => {
+    log.debug(`getJob worker[${workerId}]`);
+    const { rows: [job] } = await client.query(`SELECT * FROM "${JOBS_SCHEMA}".get_job($1, $2::text[]);`, [workerId, supportedTaskNames]);
+    return job ?? null;
+};
+exports.getJob = getJob;
+const getScheduledJob = async (client, { workerId, supportedTaskNames }) => {
+    log.debug(`getScheduledJob worker[${workerId}]`);
+    const { rows: [job] } = await client.query(`SELECT * FROM "${JOBS_SCHEMA}".get_scheduled_job($1, $2::text[]);`, [workerId, supportedTaskNames]);
+    return job ?? null;
+};
+exports.getScheduledJob = getScheduledJob;
+const runScheduledJob = async (client, { jobId }) => {
+    log.info(`runScheduledJob job[${jobId}]`);
+    try {
+        const { rows: [job] } = await client.query(`SELECT * FROM "${JOBS_SCHEMA}".run_scheduled_job($1);`, [jobId]);
+        return job ?? null;
+    }
+    catch (e) {
+        if (e?.message === 'ALREADY_SCHEDULED') {
+            return null;
+        }
+        throw e;
+    }
+};
+exports.runScheduledJob = runScheduledJob;
+const releaseScheduledJobs = async (client, { workerId, ids }) => {
+    log.info(`releaseScheduledJobs worker[${workerId}]`);
+    return client.query(`SELECT "${JOBS_SCHEMA}".release_scheduled_jobs($1, $2::bigint[]);`, [workerId, ids ?? null]);
+};
+exports.releaseScheduledJobs = releaseScheduledJobs;
+const releaseJobs = async (client, { workerId }) => {
+    log.info(`releaseJobs worker[${workerId}]`);
+    return client.query(`SELECT "${JOBS_SCHEMA}".release_jobs($1);`, [workerId]);
+};
+exports.releaseJobs = releaseJobs;

package/dist/runtime.d.ts

@@ -0,0 +1,19 @@
+import { type PgConfig } from 'pg-env';
+import type { Pool } from 'pg';
+export declare const getJobPgConfig: () => PgConfig;
+export declare const getJobPool: () => Pool;
+export declare const getJobConnectionString: () => string;
+export declare const getJobSchema: () => string;
+export declare const getJobSupportAny: () => boolean;
+export declare const getJobSupported: () => string[];
+export declare const getWorkerHostname: () => string;
+export declare const getSchedulerHostname: () => string;
+export declare const getJobGatewayConfig: () => {
+    gatewayUrl: string;
+    callbackUrl: string;
+    callbackPort: number;
+};
+export declare const getJobGatewayDevMap: () => Record<string, string> | null;
+export declare const getNodeEnvironment: () => "development" | "production" | "test";
+export declare const getJobsCallbackPort: () => number;
+export declare const getCallbackBaseUrl: () => string;

package/dist/runtime.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCallbackBaseUrl = exports.getJobsCallbackPort = exports.getNodeEnvironment = exports.getJobGatewayDevMap = exports.getJobGatewayConfig = exports.getSchedulerHostname = exports.getWorkerHostname = exports.getJobSupported = exports.getJobSupportAny = exports.getJobSchema = exports.getJobConnectionString = exports.getJobPool = exports.getJobPgConfig = void 0;
+const env_1 = require("@pgpmjs/env");
+const pg_env_1 = require("pg-env");
+const pg_cache_1 = require("pg-cache");
+const types_1 = require("@pgpmjs/types");
+const toStrArray = (v) => v ? v.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+// ---- PG config ----
+const getJobPgConfig = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    const envOnly = (0, pg_env_1.getPgEnvVars)();
+    return {
+        ...pg_env_1.defaultPgConfig,
+        ...(opts.pg ?? {}),
+        ...(opts.jobs?.pg ?? {}),
+        ...envOnly
+    };
+};
+exports.getJobPgConfig = getJobPgConfig;
+const getJobPool = () => (0, pg_cache_1.getPgPool)((0, exports.getJobPgConfig)());
+exports.getJobPool = getJobPool;
+const getJobConnectionString = () => {
+    const cfg = (0, exports.getJobPgConfig)();
+    const auth = cfg.user
+        ? `${cfg.user}${cfg.password ? `:${cfg.password}` : ''}@`
+        : '';
+    return `postgres://${auth}${cfg.host}:${cfg.port}/${cfg.database}`;
+};
+exports.getJobConnectionString = getJobConnectionString;
+// ---- Schema ----
+const getJobSchema = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    const fromOpts = opts.jobs?.schema?.schema;
+    return (fromOpts ||
+        types_1.jobsDefaults.schema?.schema ||
+        'app_jobs');
+};
+exports.getJobSchema = getJobSchema;
+// ---- SupportAny / Supported ----
+const getJobSupportAny = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    const envVal = (0, env_1.parseEnvBoolean)(process.env.JOBS_SUPPORT_ANY);
+    if (typeof envVal === 'boolean')
+        return envVal;
+    const worker = opts.jobs?.worker?.supportAny;
+    const scheduler = opts.jobs?.scheduler?.supportAny;
+    return (worker ??
+        scheduler ??
+        types_1.jobsDefaults.worker?.supportAny ??
+        true);
+};
+exports.getJobSupportAny = getJobSupportAny;
+const getJobSupported = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    const worker = opts.jobs?.worker?.supported;
+    const scheduler = opts.jobs?.scheduler?.supported;
+    return (worker ??
+        scheduler ??
+        types_1.jobsDefaults.worker?.supported ??
+        []);
+};
+exports.getJobSupported = getJobSupported;
+// ---- Hostnames ----
+const getWorkerHostname = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    return (process.env.HOSTNAME ||
+        opts.jobs?.worker?.hostname ||
+        types_1.jobsDefaults.worker?.hostname ||
+        'worker-0');
+};
+exports.getWorkerHostname = getWorkerHostname;
+const getSchedulerHostname = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    return (process.env.HOSTNAME ||
+        opts.jobs?.scheduler?.hostname ||
+        types_1.jobsDefaults.scheduler?.hostname ||
+        'scheduler-0');
+};
+exports.getSchedulerHostname = getSchedulerHostname;
+// ---- Job gateway config (generic HTTP gateway) ----
+const getJobGatewayConfig = () => {
+    const opts = (0, env_1.getEnvOptions)();
+    const gateway = opts.jobs?.gateway ?? {};
+    const defaults = types_1.jobsDefaults.gateway ?? {
+        gatewayUrl: 'http://gateway:8080',
+        callbackUrl: 'http://callback:12345',
+        callbackPort: 12345
+    };
+    return {
+        gatewayUrl: gateway.gatewayUrl ||
+            defaults.gatewayUrl,
+        callbackUrl: gateway.callbackUrl ||
+            defaults.callbackUrl,
+        callbackPort: gateway.callbackPort ??
+            defaults.callbackPort
+    };
+};
+exports.getJobGatewayConfig = getJobGatewayConfig;
+const getJobGatewayDevMap = () => {
+    const map = process.env.INTERNAL_GATEWAY_DEVELOPMENT_MAP;
+    if (!map)
+        return null;
+    try {
+        return JSON.parse(map);
+    }
+    catch (err) {
+        console.warn('[getJobGatewayDevMap] Failed to parse INTERNAL_GATEWAY_DEVELOPMENT_MAP as JSON:', err, 'Value:', map);
+        return null;
+    }
+};
+exports.getJobGatewayDevMap = getJobGatewayDevMap;
+exports.getNodeEnvironment = env_1.getNodeEnv;
+// Neutral callback helpers (generic HTTP callback)
+const getJobsCallbackPort = () => {
+    const { callbackPort } = (0, exports.getJobGatewayConfig)();
+    return callbackPort;
+};
+exports.getJobsCallbackPort = getJobsCallbackPort;
+const getCallbackBaseUrl = () => {
+    if (process.env.JOBS_CALLBACK_BASE_URL) {
+        return process.env.JOBS_CALLBACK_BASE_URL;
+    }
+    const host = process.env.JOBS_CALLBACK_HOST || 'jobs-callback';
+    const port = (0, exports.getJobsCallbackPort)();
+    return `http://${host}:${port}/callback`;
+};
+exports.getCallbackBaseUrl = getCallbackBaseUrl;

package/jest.config.js

@@ -0,0 +1,18 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: 'tsconfig.json',
+      },
+    ],
+  },
+  transformIgnorePatterns: [`/node_modules/*`],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePathIgnorePatterns: ['dist/*'],
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@constructive-io/job-utils",
+  "version": "0.5.0",
+  "description": "job utils",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/jobs/tree/master/packages/job-utils#readme",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/index.js",
+  "directories": {
+    "lib": "src",
+    "test": "__tests__"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/jobs"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:debug": "node --inspect node_modules/.bin/jest --runInBand",
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json -w"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/jobs/issues"
+  },
+  "dependencies": {
+    "@pgpmjs/env": "^2.8.3",
+    "@pgpmjs/logger": "^1.3.3",
+    "@pgpmjs/types": "^2.12.3",
+    "pg-cache": "^1.6.5",
+    "pg-env": "^1.2.2"
+  },
+  "gitHead": "86d74dc4fce9051df0d2b5bcc163607aba42f009"
+}

package/src/index.ts

@@ -0,0 +1,144 @@
+import type {
+  FailJobParams,
+  CompleteJobParams,
+  GetJobParams,
+  GetScheduledJobParams,
+  RunScheduledJobParams,
+  ReleaseScheduledJobsParams,
+  ReleaseJobsParams
+} from '@pgpmjs/types';
+
+import {
+  getJobSchema,
+  getJobPgConfig,
+  getJobPool,
+  getJobConnectionString,
+  getJobSupportAny,
+  getJobSupported,
+  getWorkerHostname,
+  getSchedulerHostname,
+  getJobGatewayConfig,
+  getJobGatewayDevMap,
+  getJobsCallbackPort,
+  getCallbackBaseUrl,
+  getNodeEnvironment
+} from './runtime';
+
+import { Logger } from '@pgpmjs/logger';
+
+const log = new Logger('jobs:core');
+
+export type PgClientLike = {
+  query<T = any>(text: string, params?: any[]): Promise<{ rows: T[] }>;
+};
+
+export {
+  getJobSchema,
+  getJobPgConfig,
+  getJobPool,
+  getJobConnectionString,
+  getJobSupportAny,
+  getJobSupported,
+  getWorkerHostname,
+  getSchedulerHostname,
+  getJobGatewayConfig,
+  getJobGatewayDevMap,
+  getJobsCallbackPort,
+  getCallbackBaseUrl,
+  getNodeEnvironment
+};
+
+const JOBS_SCHEMA = getJobSchema();
+
+export const failJob = async (
+  client: PgClientLike,
+  { workerId, jobId, message }: FailJobParams
+) => {
+  log.warn(`failJob worker[${workerId}] job[${jobId}] ${message}`);
+  await client.query(
+    `SELECT * FROM "${JOBS_SCHEMA}".fail_job($1, $2, $3);`,
+    [workerId, jobId, message]
+  );
+};
+
+export const completeJob = async (
+  client: PgClientLike,
+  { workerId, jobId }: CompleteJobParams
+) => {
+  log.info(`completeJob worker[${workerId}] job[${jobId}]`);
+  await client.query(
+    `SELECT * FROM "${JOBS_SCHEMA}".complete_job($1, $2);`,
+    [workerId, jobId]
+  );
+};
+
+export const getJob = async <T = any>(
+  client: PgClientLike,
+  { workerId, supportedTaskNames }: GetJobParams
+): Promise<T | null> => {
+  log.debug(`getJob worker[${workerId}]`);
+  const {
+    rows: [job]
+  } = await client.query(
+    `SELECT * FROM "${JOBS_SCHEMA}".get_job($1, $2::text[]);`,
+    [workerId, supportedTaskNames]
+  );
+  return (job as T) ?? null;
+};
+
+export const getScheduledJob = async <T = any>(
+  client: PgClientLike,
+  { workerId, supportedTaskNames }: GetScheduledJobParams
+): Promise<T | null> => {
+  log.debug(`getScheduledJob worker[${workerId}]`);
+  const {
+    rows: [job]
+  } = await client.query(
+    `SELECT * FROM "${JOBS_SCHEMA}".get_scheduled_job($1, $2::text[]);`,
+    [workerId, supportedTaskNames]
+  );
+  return (job as T) ?? null;
+};
+
+export const runScheduledJob = async (
+  client: PgClientLike,
+  { jobId }: RunScheduledJobParams
+): Promise<any | null> => {
+  log.info(`runScheduledJob job[${jobId}]`);
+  try {
+    const {
+      rows: [job]
+    } = await client.query(
+      `SELECT * FROM "${JOBS_SCHEMA}".run_scheduled_job($1);`,
+      [jobId]
+    );
+    return job ?? null;
+  } catch (e: any) {
+    if (e?.message === 'ALREADY_SCHEDULED') {
+      return null;
+    }
+    throw e;
+  }
+};
+
+export const releaseScheduledJobs = async (
+  client: PgClientLike,
+  { workerId, ids }: ReleaseScheduledJobsParams
+) => {
+  log.info(`releaseScheduledJobs worker[${workerId}]`);
+  return client.query(
+    `SELECT "${JOBS_SCHEMA}".release_scheduled_jobs($1, $2::bigint[]);`,
+    [workerId, ids ?? null]
+  );
+};
+
+export const releaseJobs = async (
+  client: PgClientLike,
+  { workerId }: ReleaseJobsParams
+) => {
+  log.info(`releaseJobs worker[${workerId}]`);
+  return client.query(
+    `SELECT "${JOBS_SCHEMA}".release_jobs($1);`,
+    [workerId]
+  );
+};

package/src/runtime.ts

@@ -0,0 +1,155 @@
+import { getEnvOptions, getNodeEnv, parseEnvBoolean } from '@pgpmjs/env';
+import { defaultPgConfig, getPgEnvVars, type PgConfig } from 'pg-env';
+import { getPgPool } from 'pg-cache';
+import type { Pool } from 'pg';
+import type { PgpmOptions } from '@pgpmjs/types';
+import { jobsDefaults } from '@pgpmjs/types';
+
+type Maybe<T> = T | null | undefined;
+
+const toStrArray = (v: Maybe<string>): string[] | undefined =>
+  v ? v.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+
+// ---- PG config ----
+export const getJobPgConfig = (): PgConfig => {
+  const opts: PgpmOptions = getEnvOptions();
+  const envOnly = getPgEnvVars();
+
+  return {
+    ...defaultPgConfig,
+    ...(opts.pg ?? {}),
+    ...(opts.jobs?.pg ?? {}),
+    ...envOnly
+  };
+};
+
+export const getJobPool = (): Pool =>
+  getPgPool(getJobPgConfig());
+
+export const getJobConnectionString = (): string => {
+  const cfg = getJobPgConfig();
+  const auth = cfg.user
+    ? `${cfg.user}${cfg.password ? `:${cfg.password}` : ''}@`
+    : '';
+  return `postgres://${auth}${cfg.host}:${cfg.port}/${cfg.database}`;
+};
+
+// ---- Schema ----
+export const getJobSchema = (): string => {
+  const opts: PgpmOptions = getEnvOptions();
+  const fromOpts: string | undefined = opts.jobs?.schema?.schema;
+  return (
+    fromOpts ||
+    jobsDefaults.schema?.schema ||
+    'app_jobs'
+  );
+};
+
+// ---- SupportAny / Supported ----
+export const getJobSupportAny = (): boolean => {
+  const opts: PgpmOptions = getEnvOptions();
+  const envVal = parseEnvBoolean(process.env.JOBS_SUPPORT_ANY);
+  if (typeof envVal === 'boolean') return envVal;
+
+  const worker: boolean | undefined = opts.jobs?.worker?.supportAny;
+  const scheduler: boolean | undefined = opts.jobs?.scheduler?.supportAny;
+
+  return (
+    worker ??
+    scheduler ??
+    jobsDefaults.worker?.supportAny ??
+    true
+  );
+};
+
+export const getJobSupported = (): string[] => {
+  const opts: PgpmOptions = getEnvOptions();
+  const worker: string[] | undefined = opts.jobs?.worker?.supported;
+  const scheduler: string[] | undefined = opts.jobs?.scheduler?.supported;
+
+  return (
+    worker ??
+    scheduler ??
+    jobsDefaults.worker?.supported ??
+    []
+  );
+};
+
+// ---- Hostnames ----
+export const getWorkerHostname = (): string => {
+  const opts: PgpmOptions = getEnvOptions();
+  return (
+    process.env.HOSTNAME ||
+    opts.jobs?.worker?.hostname ||
+    jobsDefaults.worker?.hostname ||
+    'worker-0'
+  );
+};
+
+export const getSchedulerHostname = (): string => {
+  const opts: PgpmOptions = getEnvOptions();
+  return (
+    process.env.HOSTNAME ||
+    opts.jobs?.scheduler?.hostname ||
+    jobsDefaults.scheduler?.hostname ||
+    'scheduler-0'
+  );
+};
+
+// ---- Job gateway config (generic HTTP gateway) ----
+export const getJobGatewayConfig = () => {
+  const opts: PgpmOptions = getEnvOptions();
+  const gateway = opts.jobs?.gateway ?? {};
+  const defaults = jobsDefaults.gateway ?? {
+    gatewayUrl: 'http://gateway:8080',
+    callbackUrl: 'http://callback:12345',
+    callbackPort: 12345
+  };
+
+  return {
+    gatewayUrl:
+      gateway.gatewayUrl ||
+      defaults.gatewayUrl,
+    callbackUrl:
+      gateway.callbackUrl ||
+      defaults.callbackUrl,
+    callbackPort:
+      gateway.callbackPort ??
+      defaults.callbackPort
+  };
+};
+
+export const getJobGatewayDevMap = ():
+  | Record<string, string>
+  | null => {
+  const map = process.env.INTERNAL_GATEWAY_DEVELOPMENT_MAP;
+  if (!map) return null;
+  try {
+    return JSON.parse(map);
+  } catch (err) {
+    console.warn(
+      '[getJobGatewayDevMap] Failed to parse INTERNAL_GATEWAY_DEVELOPMENT_MAP as JSON:',
+      err,
+      'Value:',
+      map
+    );
+    return null;
+  }
+};
+
+export const getNodeEnvironment = getNodeEnv;
+
+// Neutral callback helpers (generic HTTP callback)
+export const getJobsCallbackPort = (): number => {
+  const { callbackPort } = getJobGatewayConfig();
+  return callbackPort;
+};
+
+export const getCallbackBaseUrl = (): string => {
+  if (process.env.JOBS_CALLBACK_BASE_URL) {
+    return process.env.JOBS_CALLBACK_BASE_URL;
+  }
+  const host = process.env.JOBS_CALLBACK_HOST || 'jobs-callback';
+  const port = getJobsCallbackPort();
+  return `http://${host}:${port}/callback`;
+};

package/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "module": "es2022",
+    "rootDir": "src/",
+    "declaration": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src/"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "**/*.spec.*", "**/*.test.*"]
+}