{"_id":"@api-platform/mercure","_rev":"2-39123a14a81b7562f6fcba44af4eced9","name":"@api-platform/mercure","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@api-platform/mercure","version":"1.0.0","author":{"name":"soyuka"},"license":"MIT","_id":"@api-platform/mercure@1.0.0","maintainers":[{"name":"dunglas","email":"dunglas@gmail.com"},{"name":"simperfit","email":"hamza.simperfit@gmail.com"},{"name":"mysiar","email":"psynowiec@gmail.com"},{"name":"meyerbaptiste","email":"baptiste.meyer@gmail.com"},{"name":"teohhanhui","email":"teohhanhui@gmail.com"},{"name":"soyuka","email":"soyuka@gmail.com"}],"homepage":"https://edge-side-api.rocks/mercure","dist":{"shasum":"d3e42e3e62fd50fc8f34446d37f9ff0071b32f72","tarball":"https://registry.npmjs.org/@api-platform/mercure/-/mercure-1.0.0.tgz","fileCount":6,"integrity":"sha512-hOx7rLUH0/bDF35RQjdFIQO/blzXTPGoUum6JF2Ms/RZhGoxnZlDj6WIisdMK8dELuOzslcGL39QeVuYX26W3A==","signatures":[{"sig":"MEYCIQDqvo46qBHpF/11EHMqYiyFUr8s+mrHWIWqnDWqTn8e2wIhANi45UPb9f5OicAKHV5NpNsdlnN7OXdn+a8uddx86FbS","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":6444},"main":"mercure.js","gitHead":"52cd0d4e27c5f4384a5ff24d26fc3ad938417ee5","scripts":{"tsc":"tsc","lint":"eslint mercure.ts","test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"dunglas","email":"dunglas@gmail.com"},"_npmVersion":"10.8.2","description":"Mercure handler","directories":{},"_nodeVersion":"22.6.0","dependencies":{"eventsource":"^2.0.2","urlpattern-polyfill":"^10.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.3.0","globals":"^14.0.0","@eslint/js":"^9.3.0","typescript":"^5.4.5","typescript-eslint":"^7.10.0","@types/eventsource":"^1.1.15"},"_npmOperationalInternal":{"tmp":"tmp/mercure_1.0.0_1724155106348_0.22940288563725741","host":"s3://npm-registry-packages"}},"2.0.0":{"_id":"@api-platform/mercure@2.0.0","dist":{"shasum":"8a00b9f0f7fba3f670f929fe417dfd41f02067dc","tarball":"https://registry.npmjs.org/@api-platform/mercure/-/mercure-2.0.0.tgz","fileCount":7,"integrity":"sha512-GW2VBNhoyDcd98oQvRRYNTwi1yqwlzB1sVmDcu49lHrlP24cvdScy1dCfYSIHFB5YtC8/KLjp06ShEZjvCI6Ag==","signatures":[{"sig":"MEUCIQDRidRutv7R07mgA/kr5b4E6ghWVMAsllrO0Fk0kJodTgIgOeicTkDPUv7gdybH11CIEMrjPF0yBgiVfeRS0k9l0p8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCV98nqM2T6o51z/9K7iBXuPU3lm7Eev9mTBqvRkgHdTgIhANDgj9kJJLA2/JhLjwt1XQldiZjyMZ9xiv0K7u1xLszx"}],"unpackedSize":22903},"main":"mercure.js","name":"@api-platform/mercure","author":{"name":"soyuka"},"gitHead":"f2bc9b5186d683ef94f398b55cf1fb4581650e51","license":"MIT","scripts":{"tsc":"tsc","lint":"eslint mercure.ts","test":"echo \"Error: no test specified\" && exit 1"},"version":"2.0.0","_npmUser":{"name":"soyuka","email":"soyuka@gmail.com"},"homepage":"https://edge-side-api.rocks/mercure","_npmVersion":"lerna/8.1.2/node@v26.9.0+x64 (linux)","description":"Mercure handler","directories":{},"maintainers":[{"name":"dunglas","email":"dunglas@gmail.com"},{"name":"simperfit","email":"hamza.simperfit@gmail.com"},{"name":"mysiar","email":"psynowiec@gmail.com"},{"name":"meyerbaptiste","email":"baptiste.meyer@gmail.com"},{"name":"teohhanhui","email":"teohhanhui@gmail.com"},{"name":"soyuka","email":"soyuka@gmail.com"}],"_nodeVersion":"26.9.0","dependencies":{"eventsource":"^5.1.1","urlpattern-polyfill":"^10.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.3.0","globals":"^14.0.0","@eslint/js":"^9.3.0","typescript":"^5.4.5","typescript-eslint":"^7.10.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mercure_2.0.0_1789649625084_0.8073502132467154"}}},"time":{"created":"2024-08-20T11:58:26.231Z","modified":"2026-09-17T12:53:45.421Z","1.0.0":"2024-08-20T11:58:26.525Z","2.0.0":"2026-09-17T12:53:45.173Z"},"author":{"name":"soyuka"},"license":"MIT","homepage":"https://edge-side-api.rocks/mercure","description":"Mercure handler","maintainers":[{"name":"dunglas","email":"dunglas@gmail.com"},{"name":"simperfit","email":"hamza.simperfit@gmail.com"},{"name":"mysiar","email":"psynowiec@gmail.com"},{"name":"meyerbaptiste","email":"baptiste.meyer@gmail.com"},{"name":"teohhanhui","email":"teohhanhui@gmail.com"},{"name":"soyuka","email":"soyuka@gmail.com"}],"readme":"# @api-platform/mercure\n\n`@api-platform/mercure` is an EventSource wrapper that [discovers a Mercure Hub](https://mercure.rocks/spec#discovery) according to the Link headers and handles subscriptions for you.\n\n```javascript\nimport mercure, { close } from \"@api-platform/mercure\";\n\nconst res = await mercure('https://localhost/authors/1', {\n    onUpdate: (author) => console.log(author)\n})\n\nconst author = res.then(res => res.json())\n\n// Close if you need to \nhistory.onpushstate = function(e) {\n    close('https://localhost/authors/1')\n}\n```\n\nAssuming `/authors/1` returned:\n\n```\nLink: <https://localhost/authors/1>; rel=\"self\"\nLink: <https://localhost/.well-known/mercure>; rel=\"mercure\"\n```\n\nA new `EventSource` is created by subscribing to the topic `https://localhost/authors/1` on the Hub `https://localhost/.well-known/mercure`. \n\n## Installation\n\n```shell\nnpm install @api-platform/mercure\n```\n\n## Usage\n\nUse `mercure` like [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API):\n\n```javascript\nimport mercure, { close } from \"@api-platform/mercure\";\n\nconst res = await mercure('https://localhost/authors/1', {\n    onUpdate: (author) => console.log(author)\n})\n\nconst author = res.then(res => res.json())\n```\n\nAvailable options:\n\n- `onError` on EventSource error callback\n- `EventSource` to provide your own `EventSource` constructor\n- `fetchFn` to provide your own fetch function, it needs to return a response so that we can read headers\n- `parse` to read the payload yourself, `JSON.parse` by default. A parse error goes to `onError`\n- `rawEvent` to receive the whole `MessageEvent` instead of the payload\n\nThis can be used in conjunction with [@api-platform/ld](/linked-data) as the `fetchFn`.\n\n### Subscribing to a family of topics\n\nA hub takes matchers rather than resources, and `subscribe` returns the function that ends the subscription:\n\n```javascript\nimport mercure, { hub } from \"@api-platform/mercure\";\n\nconst authors = hub('https://localhost/.well-known/mercure')\n\nconst unsubscribe = authors.subscribe({type: 'urlpattern', value: '/authors/:id'}, {\n    onUpdate: (author) => console.log(author)\n})\n```\n\nEvery resource you then fetch with `mercure()` that this pattern covers joins that subscription instead of opening one of its own. The family belongs to the caller that asked for it: `close(topic)` on a covered resource removes that callback alone, and the subscription ends when you call the returned function.\n\nThe hub matches the pattern, so you also receive updates for topics you never fetched. [URL Patterns](https://mercure.rocks/docs/1.0/concepts/topics-and-matchers) support named groups (`:id`), wildcards (`*`), regular expression constraints and optional segments.\n\n`hub` takes the connection options, `headers`, `withCredentials` and `EventSource`, because they belong to the stream and not to one subscription. `subscribe(hubUrl, matcher, options)` is the same call in one step.\n\n### Discovery\n\nThe `rel=\"mercure\"` Link header can carry target attributes, and the client honours two of them.\n`last-event-id` is the identifier of the last event the publisher had dispatched when it generated\nthe resource: it goes to the hub as a `last_event_id` query parameter, so an update published\nbetween that moment and the subscription is not lost. `type` is the Server-Sent Events event type\nthe updates carry, and the client listens for it in addition to the default one.\n\n### One connection per hub\n\nResources served by the same hub share one connection. An SSE frame does not name a topic, so every callback registered on that hub receives every update, and the payload is what tells them apart. With JSON-LD, dispatch on `@id`.\n\nThe connection uses the options of the call that opened it. A later call on the same hub adds its callbacks, but it does not change the credentials, the headers or the `EventSource` implementation of a stream that already runs.\n\n### Examples\n\nSee [our Tanstack query example](https://github.com/api-platform/esa/blob/main/tests-server/mercure.html) or the source code of our [home page](https://github.com/api-platform/esa/blob/main/api/public/index.js).\n","readmeFilename":"README.md"}