lib.jobs

@lssm-tech/lib.jobs

Website: https://contractspec.io

Background jobs and scheduler module for ContractSpec applications.

What It Provides

• Layer: lib.
• Consumers: bundles.
• src/contracts/ contains contract specs, operations, entities, and registry exports.
• src/handlers/ contains handlers or demo adapters wired to contract surfaces.
• src/contracts/ contains contract specs, operations, entities, and registry exports.
• src/handlers/ contains handlers or demo adapters wired to contract surfaces.

Installation

npm install @lssm-tech/lib.jobs

or

bun add @lssm-tech/lib.jobs

Usage

Import the root entrypoint from @lssm-tech/lib.jobs, or choose a documented subpath when you only need one part of the package surface.

mapPendingV1JobToDurableQueueV2 is the narrow compatibility bridge for legacy JobQueue jobs. It maps only pristine pending jobs whose tenant, trace, dedupe, retry, priority, schema, operation, order, replay, and workload semantics are supplied explicitly. Mutable execution state, metadata, user identity, timeouts, secret-bearing payloads, oversized payloads, and cyclic values fail closed as unsupported; the bridge never invents authority.

Architecture

• src/contracts/ contains contract specs, operations, entities, and registry exports.
• src/entities/ contains domain entities and value objects.
• src/events.ts is package-level event definitions.
• src/handlers/ contains handlers or demo adapters wired to contract surfaces.
• src/index.ts is the root public barrel and package entrypoint.
• src/jobs.capability.ts defines a capability surface.
• src/jobs.feature.ts defines a feature entrypoint.

Public Entry Points

• Export . resolves through ./src/index.ts.
• Export ./contracts resolves through ./src/contracts/index.ts.
• Export ./entities resolves through ./src/entities/index.ts.
• Export ./events resolves through ./src/events.ts.
• Export ./handlers resolves through ./src/handlers/index.ts.
• Export ./handlers/gmail-sync-handler resolves through ./src/handlers/gmail-sync-handler.ts.
• Export ./handlers/ping-job resolves through ./src/handlers/ping-job.ts.
• Export ./handlers/storage-document-handler resolves through ./src/handlers/storage-document-handler.ts.
• Export ./jobs.capability resolves through ./src/jobs.capability.ts.
• Export ./jobs.feature resolves through ./src/jobs.feature.ts.
• The package publishes 21 total export subpaths; keep docs aligned with package.json.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.

Notes

• Queue and scheduler interfaces are adapter boundaries — do not leak implementation details.
• Job entity schema is shared across consumers; changes require migration awareness.
• Capability contract (jobs.capability) is public API — treat as a breaking-change surface.

Transactional outbox

./outbox/types owns the storage-agnostic transactional outbox contract, and ./outbox/in-memory owns its existing single-process reference adapter. ./outbox/dispatcher owns the at-least-once OutboxDispatcher (claim, deliver, mark delivered/failed/dead-lettered) and ./outbox/backoff owns nextAttemptAt (scheduled retry with ±10% jitter); both moved unchanged from the Company runtime. ./outbox exports all four. Enqueue remains atomic with the supplied transaction; claim locks, row-id deduplication and caller actor/tenant/trace propagation are unchanged. Persistent storage and domain dispatch remain caller-owned. Company runtime paths (./outbox, ./outbox/backoff, ./outbox/dispatcher, ./outbox/types, ./outbox/in-memory) remain identity-preserving compatibility aliases.

Canonical queue contract

The explicit ./queue/contract leaf owns the complete existing Job, JobQueue, enqueue, handler, status, statistics and retry contracts and the original DEFAULT_RETRY_POLICY, calculateBackoff and defineJobType runtime helpers. Legacy jobs/queue forwards to these same values and declarations. Queue adapters, registration calls, scheduling, authority and provider effects retain their existing owners and behavior; this move does not activate a worker.

The explicit ./queue/defined-contract-job leaf retains the complete original DefinedJob contract and its registerDefinedJob validator/handler callback. It is distinct from the existing queue/register-defined-job adapter, whose payload-copy body remains unchanged. Source and tests consume actual Core result/contracts and Orchestration durable queue identities; no adapter or registration is replaced.

The explicit @lssm-tech/lib.jobs/spec leaf owns the existing job specification, JobSpecRegistry and defineJob helper. Legacy contracts-spec/jobs/spec imports forward to these identical values. Importing this leaf does not start a worker.