{"id":19163229,"url":"https://github.com/oada/jobs","last_synced_at":"2025-08-16T23:05:00.730Z","repository":{"id":39759541,"uuid":"235936727","full_name":"OADA/jobs","owner":"OADA","description":"A library for oada job based microservices","archived":false,"fork":false,"pushed_at":"2025-04-02T19:30:06.000Z","size":8064,"stargazers_count":0,"open_issues_count":22,"forks_count":1,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-02T20:32:06.795Z","etag":null,"topics":["oada"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OADA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-24T04:02:14.000Z","updated_at":"2025-04-02T19:30:03.000Z","dependencies_parsed_at":"2024-02-12T23:30:24.798Z","dependency_job_id":"d5600a30-774c-42c0-942a-f5aeb998a30c","html_url":"https://github.com/OADA/jobs","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/OADA/jobs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fjobs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fjobs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fjobs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fjobs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OADA","download_url":"https://codeload.github.com/OADA/jobs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fjobs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270781393,"owners_count":24643820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oada"],"created_at":"2024-11-09T09:14:32.803Z","updated_at":"2025-08-16T23:05:00.677Z","avatar_url":"https://github.com/OADA.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @oada/oada-jobs\n\nA library that abstracts away managing an OADA services job queue.\n\n## Install\n\n`$ yarn add @oada/oada-jobs`\n\n## Notes / Todos\n\n1. Only use **unversioned links** in job queues (which is really what you want\n   anyway). It is a TODO to deal with change notifications other than merging\n   and deleting links into the queue.\n2. The promise your work function returns should implement the `cancel` method\n   to have job timeouts work as expected. If a promise is timed out, but the\n   work function continues, the job will still be moved to `jobs-failure` and\n   the status set to `failure`. However; updates from the work function that\n   occur after the timeout will still be committed. The result of the work\n   function is lost.\n3. Add a list of resources which should have the jobs linked to in their meta at\n   completion. This is a side effect, but often useful.\n\n## Basic usage\n\n```typescript\nconst apiKey = process.env.apiKey;\nassert(apiKey, 'set ENV `apiKey` to the service sendgrid API key');\nimport { config } from 'dotenv';\nimport debug from 'debug';\n\nimport { Service, Json } from '@oada/jobs';\n\nconfig();\nconst domain = process.env.domain;\nassert(domain, 'Set ENV `domain` to domain storing the service configuration');\nconst token = process.env.token;\nassert(token, 'Set ENV `token` to the service token');\n\nconst info = debug('service-name:info');\n\n// Allow up to 10 in-flight OADA requests at once\nconst service = new Service('service-name', domain, token, 10);\n\n// Run work function on all \"email\" type jobs. Timeout in 10 seconds.\nservice.on(\n  'email',\n  10 * 1000,\n  async (job, { jobId, log, oada }): Promise\u003cJson\u003e =\u003e {\n    info(`[Job ${jobId}] μservice triggered`);\n\n    log.info('started', 'Job started');\n    const config = job.config;\n\n    assertConfig(config);\n    log.trace('confirmed', 'Job config confirmed');\n\n    info(`[Job ${jobId}] Doing work`);\n    log.debug('working', 'Working');\n\n    // `oada` already has the correct token loaded\n    const r = await oada.get({\n      path: `/bookmarks/thing`,\n    });\n\n    return { coolThing: r.data.thing };\n  },\n);\n\nservice.start().catch((e: unknown) =\u003e {\n  console.error(e);\n});\n```\n\n### Configuring queues\n\nService queues configuration lives at\n`/bookmarks/services/\u003cservice-name/queueus` with the service token\n(`process.env.token` from the example above). To tell @oada/jobs to watch a\nqueue POST something like:\n\n```json\n{\n  \"domain\": \"oada.example.org\",\n  \"token\": \"jfdjxkfassr3423544511243fzdgsd\"\n}\n```\n\nTo stop watching a queue, DELETE the queue object in the queues list `DELETE /bookmarks/services/\u003cservice-name\u003e/queues/\u003cqueue-id\u003e`.\n\n### Adding jobs\n\n@oada/jobs will call the registered work function for the type of any job added\nto one of its queues. The return value is stored on the job object. Any logged\nvalue is stored on the job object. When the work function returns, the job will\nbe moved to the `jobs-success` or `jobs-failure` lists.\n\nBe sure to set the `OADA_JOBS_LOGGING` environmental variable if you want to log\n\"debug\" and/or \"trace\" logs.\n\n## Batch jobs\n\nIt seems unlikely `@oada/jobs` can reasonable manage \"batch\" jobs for you -- its\nnot clear there is a single \"correct\" batch management.\n\nHowever, one COULD imagine something like:\n\n```typescript\n  Service.getJobs(type: string, batchWork: (queueId: QueueId, jobs: Array\u003c{job: Job, context: WorkerContext}\u003e) =\u003e Promise\u003cJson\u003e)`\n```\n\nThis would be used in place of `Service.on(type, work)`.\n\nThe implementor of a batch service would need to develop a work function\nprocesses all Jobs in `jobs` at once, uses the WorkerContext to update each job,\nand then result a overall result which will be applied to all jobs in the batch.\n\nThe service would need to schedule calls to `getJobs` however it sees fit.\n\n## General idea\n\nThe `Service` class manages the overall service. You register work functions of\ncertain job types with it. The `Service` class watches a list of service queues\n(`/bookmarks/services/\u003cservice-name\u003e/queues`) using the service token. Each\nqueue item (a domain and token) results in a `Queue` class.\n\nThe `Queue` class watches a particular job queue\n(`/bookmarks/services/\u003cservice-name\u003e/jobs`) using the associated token from the\nService queue list. Each job that created results in a `Runner` class.\n\nThe `Runner` class is sort of like a Promise for an OADA job. It runs the work\nfunction and maintains the Job's state in the OADA store. Note, the OADAClient\nthat `Runner` provides to the work function is already adjusted for the correct\ntoken. The `work` function should just use the OADAClient without regard for the\ntoken.\n\nSome other useful classes:\n\n`Logger` -- Given to the work function. This exposes methods to add updates to\nthe Job object in the OADA store. Set OADA_JOBS_LOGGING to something like\n\"debug,trace\" to enable the debug and trace logs, respectively.\n\n`Job` -- Given to the work function. Stores the job type, config, etc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foada%2Fjobs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foada%2Fjobs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foada%2Fjobs/lists"}