lib.jobs
Background jobs and scheduler module for ContractSpec applications
@lssm-tech/lib.jobsbun add @lssm-tech/lib.jobsManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
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.tsis package-level event definitions.src/handlers/contains handlers or demo adapters wired to contract surfaces.src/index.tsis the root public barrel and package entrypoint.src/jobs.capability.tsdefines a capability surface.src/jobs.feature.tsdefines a feature entrypoint.
Public Entry Points
- Export
.resolves through./src/index.ts. - Export
./contractsresolves through./src/contracts/index.ts. - Export
./entitiesresolves through./src/entities/index.ts. - Export
./eventsresolves through./src/events.ts. - Export
./handlersresolves through./src/handlers/index.ts. - Export
./handlers/gmail-sync-handlerresolves through./src/handlers/gmail-sync-handler.ts. - Export
./handlers/ping-jobresolves through./src/handlers/ping-job.ts. - Export
./handlers/storage-document-handlerresolves through./src/handlers/storage-document-handler.ts. - Export
./jobs.capabilityresolves through./src/jobs.capability.ts. - Export
./jobs.featureresolves 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 devbun run build— contractspec-bun-build buildbun run lint— bun lint:fixbun run lint:check— biome check .bun run lint:fix— biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .bun run typecheck— tsgo --noEmitbun run publish:pkg— bun publish --tolerate-republish --ignore-scripts --verbosebun run publish:pkg:canary— bun publish:pkg --tag canarybun run clean— rimraf dist .turbobun run build:bundle— contractspec-bun-build transpilebun run build:types— contractspec-bun-build typesbun 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.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
11 declarations
@lssm-tech/lib.orchestration-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@aws-sdk/client-sqs^3.1135.0
@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗@lssm-tech/lib.crypto-utilsworkspace:^
Read the package manual ↗@lssm-tech/lib.knowledgeworkspace:^
Read the package manual ↗
Declared capabilities
Background jobs and scheduler module for ContractSpec applications
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .prebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit