{"id":19066529,"url":"https://github.com/geut/saga","last_synced_at":"2025-04-28T12:30:01.882Z","repository":{"id":88986177,"uuid":"171144520","full_name":"geut/saga","owner":"geut","description":"A helper module to share operations between peers built on top of hyperdb.","archived":false,"fork":false,"pushed_at":"2019-02-19T03:27:37.000Z","size":6,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-18T16:17:36.739Z","etag":null,"topics":["dat","helper","p2p"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/geut.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-02-17T16:29:48.000Z","updated_at":"2022-01-29T19:18:15.000Z","dependencies_parsed_at":"2023-06-13T10:45:12.525Z","dependency_job_id":null,"html_url":"https://github.com/geut/saga","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geut%2Fsaga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geut%2Fsaga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geut%2Fsaga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geut%2Fsaga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geut","download_url":"https://codeload.github.com/geut/saga/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251313313,"owners_count":21569405,"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":["dat","helper","p2p"],"created_at":"2024-11-09T00:57:15.001Z","updated_at":"2025-04-28T12:30:01.870Z","avatar_url":"https://github.com/geut.png","language":"JavaScript","readme":"# @geut/saga\n\n\u003e A helper module to share operations between peers built on top of\n\u003e hyperdb.\n\n---\n![npm version badge](https://badge.fury.io/js/%40geut%2Fsaga.svg)\n\n## Install\n\n`npm install @geut/saga`\n\n## Usage\n\nFirst, instantiate saga:\n\n`const saga = Saga(ram, publicKey, username);`\n\nThen, we will need a swarm of peers:\n\n```javascript\nconst sw = swarm({\n  id: username,\n  stream: () =\u003e {\n    return saga.replicate();\n  }\n});\n\nsw.join(signalhub(discoveryKey, signalUrls), webrtcOpts);\n\nsw.on('connection', async peer =\u003e {\n  try {\n    await saga.connect(peer);\n  } catch (err) {\n    console.log(err);\n  }\n});\n```\n_Hint:_ You can use [`@geut/discovery-swarm-webrtc`](https://github.com/geut/discovery-swarm-webrtc).\n\n_Hint2:_ You will need a signal server, like [signalhubws](https://github.com/soyuka/signalhubws).\n\nAfter that, you are ready to use `saga`. This include, sending and receiving operations that you can apply on each peer.\n\n## API\n\n### initialize\n\n\u003e Returns a `promise`.\n\nUsed to trigger hyperdb creation and setup the watch for operations.\n\n### connect\n\n\u003e `Peer` | Required. The peer must have a `remoteUserData` property.\n\nThis will **authorize** the peer to be a writer. Emits a `join` event\nalong with peer data. Finally, if the peer leaves, it will also emit\na `leave` event, indicating the peer.\n\n### replicate\n\nIt will replicate the stream. Uses hyperdb replicates method under the\nhood with some fixed values:\n\n```javascript\n{\n  live: true,\n  userData: JSON.stringify({\n    key: this.db.local.key,\n    username: this.username,\n    timestamp: this.timestamp\n  })\n}\n```\n\n### writeOperation\n\n\u003e `Object` | Optional\n\nUse this method to send a new operation to every peer. It will also add\nthe username of the sender and a timestamp.\n\n## Events\n\n`saga` inherits from node.js `EventEmitter`. It will emit the following\nevents:\n\n### join\n\n\u003e `peerData: Object`\n\nAfter authorizing a new peer, saga will emit a join event with some peer\ndata. This is triggered by the `connect` method (see above).\n\n### leave\n\n\u003e `peerData: Object`\n\nAfter a peer leaves, the leave event will be emitted with some peer data.\n\n### operation\n\n\u003e `Object`\n\nThe operation event will be emitted after reading feed history changes\n(see hyperdb) caused by new operations arrival. You can listen to this\nevent to retrieve the latest operations that you can apply to regenerate\nthe distributed state between peers. The event will contain an object with\nthe `username` of the sender, a `timestamp` and the `operation`.\n\n## Motivation\n\nThe idea came up after playing with [olaf](https://github.com/geut/olaf),\na P2P Dat powered chat application. That is when `saga` first appears.\nLater we were playing with the idea of CRDT based editor, also Dat\npowered. I wanted to re-use some parts and saga was my first option.\nI only need to make some subtle changes, like mostly renaming messages to\noperations in order to be more generic.\n\nWhen creating P2P apps, the absence of a centralized server, empowers\npeers (former _clients_). Since now they can share data between each\nother, it is useful to have a way to re-create locally changes that have\nhappened in another peer, this is were you can use `saga`. Also keep in\nmind that libraries like\n[Automerge](https://github.com/automerge/automerge) are a great match!\n\n\n---\nBrought to you by **GEUT LABS ʘ**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeut%2Fsaga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeut%2Fsaga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeut%2Fsaga/lists"}