{"id":15681107,"url":"https://github.com/kettanaito/until-connected","last_synced_at":"2025-05-07T11:46:57.833Z","repository":{"id":217679222,"uuid":"744516282","full_name":"kettanaito/until-connected","owner":"kettanaito","description":"Wait for a connection at the given target without making any requests.","archived":false,"fork":false,"pushed_at":"2024-01-25T11:22:16.000Z","size":44,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-28T11:25:13.937Z","etag":null,"topics":["connection","retry","server","test","tests","timeout","wait"],"latest_commit_sha":null,"homepage":"https://npm.im/until-connected","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kettanaito.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-01-17T13:12:14.000Z","updated_at":"2024-10-08T17:05:18.000Z","dependencies_parsed_at":"2024-01-25T12:42:21.095Z","dependency_job_id":null,"html_url":"https://github.com/kettanaito/until-connected","commit_stats":null,"previous_names":["kettanaito/until-connected"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kettanaito%2Funtil-connected","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kettanaito%2Funtil-connected/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kettanaito%2Funtil-connected/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kettanaito%2Funtil-connected/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kettanaito","download_url":"https://codeload.github.com/kettanaito/until-connected/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252826496,"owners_count":21810121,"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","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":["connection","retry","server","test","tests","timeout","wait"],"created_at":"2024-10-03T16:49:29.726Z","updated_at":"2025-05-07T11:46:57.813Z","avatar_url":"https://github.com/kettanaito.png","language":"TypeScript","readme":"# Until Connected\n\nWait for a connection at the given target without making any requests.\n\n## Why this package?\n\nMost packages that concerns themselves with awaiting a particular connection do so by making a `HEAD`/`GET` request to the address. This means that if you are awaiting an application that _has some lgic_ in its root (`/`) route, such an await mechanism will trigger that logic.\n\nConsider this:\n\n```js\n// app.js\nimport express from 'express'\n\nconst app = express()\n\napp.get('/', async (req, res) =\u003e {\n  const response = await fetch('https://example.com')\n  res.json(await response.json())\n})\n\napp.listen(3000)\n```\n\nTo serve the root route, this application does an additional request to `https://example.com`. Now, if you try to await `127.0.0.1:3000` by conventional methods, any ping requests to `/` will also trigger the `GET https://example.com`.\n\nThis problem quickly becomes apparent if you wish to await a JavaScript application before testing it. If your application needs third-party resources to render its root route, awaiting it by conentional methods will force those resources to be fetched. This is highly undesirable.\n\nThis module solves this problem by relying on establishing a socket connection (using `net.connect()` from Node.js) to verify the application is running instead of making any requests to it. This way, it doesn't trigger any requests in your application while allowing you to reliably wait until it's up and running.\n\n## Usage\n\n```sh\nnpm i until-connected\n```\n\n```js\nimport { exec } from 'node:child_process'\nimport { untilConnected } from 'until-connected'\n\nasync function runServerThenTest(runCommand, url, testCommand) {\n  // Start the application server.\n  exec(runCommand)\n\n  // Wait for the application server to be running.\n  await untilConnected({ target: url })\n\n  // Run the tests.\n  exec(testCommand)\n}\n```\n\n## API\n\n### `untilConnected(options)`\n\nReturns a Promise that resolves if the connection was successful and rejects if it wasn't, given additional options.\n\n```js\n// Wait for the application on port 3000.\nawait untilConnected({ target: 3000 })\n```\n\nThe returned Promise rejects if the connection couldn't be established or if it fails for any other reason. The original connection error is exposed under `error.cause` on the Promise:\n\n```js\nuntilConnected({ target: 3000 }).catch((error) =\u003e {\n  console.log('Original connection error:', error.cause)\n})\n```\n\n## Options\n\n### `target`\n\n- _Required_. `number | string | URL`\n\nA target to await. Supports a standalone port number and a full URL string or a `URL` instance.\n\n```js\n// Wait for the application on port 3000.\nawait untilConnected({\n  target: 3000,\n})\n\n// Wait for the application at the address.\nawait untilConnected({\n  target: 'http://localhost:56789',\n})\n```\n\n### `maxRetries`\n\n- `number` (default: 5)\n\nMaximum number of retries before rejecting the connection Promise.\n\n```js\nawait untilConnected({\n  port: 3000,\n  // By using 1, the wait function will reject\n  // if the connection fails after the first attempt.\n  maxRetries: 1,\n})\n```\n\n### `connectionInterval`\n\n- `number` (in ms)\n\nAn interval between connection retries.\n\n```js\nawait untilConnected({\n  target: 3000,\n  // Wait for 500ms after a failed connection\n  // before attempting another connection.\n  connectionInterval: 500,\n})\n```\n\n## License\n\nMIT.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkettanaito%2Funtil-connected","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkettanaito%2Funtil-connected","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkettanaito%2Funtil-connected/lists"}