{"id":13941242,"url":"https://github.com/RangerMauve/hyper-sdk","last_synced_at":"2025-07-20T04:31:02.019Z","repository":{"id":37080244,"uuid":"190758075","full_name":"RangerMauve/hyper-sdk","owner":"RangerMauve","description":"Make your own hyper apps!","archived":false,"fork":false,"pushed_at":"2025-05-27T13:35:11.000Z","size":278,"stargazers_count":297,"open_issues_count":5,"forks_count":46,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-06-30T15:18:23.828Z","etag":null,"topics":["dweb","hypercore","hypercore-protocol","p2p"],"latest_commit_sha":null,"homepage":"https://www.youtube.com/watch?v=HyHk4aImd_I\u0026list=PL7sG5SCUNyeYx8wnfMOUpsh7rM_g0w_cu\u0026index=20","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RangerMauve.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-06-07T14:33:34.000Z","updated_at":"2025-05-27T13:35:13.000Z","dependencies_parsed_at":"2024-04-08T18:41:46.609Z","dependency_job_id":"e7315981-3f8c-4188-8628-3ba43fa539cb","html_url":"https://github.com/RangerMauve/hyper-sdk","commit_stats":{"total_commits":237,"total_committers":24,"mean_commits":9.875,"dds":0.3755274261603375,"last_synced_commit":"0af9e4de1b7c4e6929cc225f7708f26eec1aacc0"},"previous_names":["datproject/sdk"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/RangerMauve/hyper-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RangerMauve%2Fhyper-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RangerMauve%2Fhyper-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RangerMauve%2Fhyper-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RangerMauve%2Fhyper-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RangerMauve","download_url":"https://codeload.github.com/RangerMauve/hyper-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RangerMauve%2Fhyper-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266067256,"owners_count":23871324,"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":["dweb","hypercore","hypercore-protocol","p2p"],"created_at":"2024-08-08T02:01:14.692Z","updated_at":"2025-07-20T04:31:02.000Z","avatar_url":"https://github.com/RangerMauve.png","language":"JavaScript","readme":"# hyper-sdk\n\nA Software Development Kit for the [hypercore-protocol](https://hypercore-protocol.org/)\n\n## Why use this?\n\nHypercore-protocol and it's ecosystem consists of a bunch of low level building blocks for working with data in distributed applications. Although this modularity makes it easy to mix and match pieces, it adds complexity when it comes to actually building something.\n\nThe Hyper SDK combines the lower level pieces of the Hyper stack into high level APIs that you can use across platforms so that you can focus on your application rather than the gritty details of how it works.\n\n## Goals\n\n- High level API\n- Cross-platform with same codebase\n  - ✔ [Node.js](https://nodejs.org/en)\n  - ✔ [Electron](https://www.electronjs.org/)\n  - ✔ [Pear](https://docs.pears.com/)\n  - 🏗️ Web (PRs welcome)\n\n## Installation\n\nMake sure you've set up [Node.js](https://nodejs.org/).\n\n```shell\nnpm install --save hyper-sdk\n# or yarn\n```\n\n```js\nimport * as SDK from \"hyper-sdk\"\n```\n\n## API\n\n### SDK.create()\n\n```JavaScript\nconst sdk = await SDK.create({\n  // This argument is mandatory since Hypercore no longer support in-memory\n  // Check out the env-paths module for application specific path storage\n  storage: './hyper-sdk',\n\n  // This controls whether the SDK will automatically start swarming when loading a core via `get`\n  // Set this to false if you want to have more fine control over peer discovery\n  autoJoin: true,\n\n  // Specify options to pass to the Corestore constructor\n  // The storage will get derived from the `storage` parameter\n  // https://github.com/hypercore-protocol/corestore/\n  corestoreOpts: {},\n\n  // Specify options to pass to the hyperswarm constructor\n  // The keypair will get derived automatically from the corestore\n  // https://github.com/hyperswarm/hyperswarm\n  swarmOpts: {},\n})\n```\n\n### sdk.publicKey\n\nThe public key used for identifying this peer in the hyperswarm network.\n\nThis is a 32 byte buffer which can be use in conjunction with `sdk.joinPeer()` to connect two peers directly together.\n\n### sdk.connections\n\nThe list of active connections to other peers, taken from hyperswarm.\n\n### sdk.peers\n\nThe list of active peers.\n\nEach peer has a `publicKey`, and list of `topics`\n\nYou can find more docs in the [hyperswarm](https://github.com/hyperswarm/hyperswarm#peerinfo-api) repo.\n\n### sdk.cores\n\nList of active Hypercores.\n\n### sdk.on('peer-add', peerInfo) / sdk.on('peer-remove', peerInfo)\n\nYou can listen on when a peer gets connected or disconnected with this event.\n\nYou can find more docs in the [hyperswarm](https://github.com/hyperswarm/hyperswarm#peerinfo-api) repo.\n\n```JavaScript\nsdk.on('peer-add', (peerInfo) =\u003e {\n  console.log('Connected to', peerInfo.publicKey, 'on', peerInfo.topics)\n})\nsdk.on('peer-add', (peerInfo) =\u003e {\n  console.log('Disconnected from')\n})\n```\n\n### sdk.get()\n\nYou can initialize a [Hypercore](https://github.com/hypercore-protocol/hypercore) instance by passing in a key, a name to derive a key from, or a URL containing either a key or a DNS name.\n\nUnlike corestore, you may not initialize a hypercore from a `null` key since everything must be derivable or loadable.\n\nUnless `autoJoin` is set to `false`, the peer discovery will be automatically started for the core.\n\n```JavaScript\n// Derive a key from a \"name\"\nconst core = await sdk.get('example name')\n\n// Resolve DNS to a hypercore\nconst core = await sdk.get('hyper://example.mauve.moe')\n\n// Buffer key, 32 bytes of 0's\nconst core = await sdk.get(b4a.alloc(32, 0))\n\n// Hex key, equivalent to 32 bytes of zeros\nconst core = await sdk.get('hyper://0000000000000000000000000000000000000000000000000000000000000000')\n\n// z32 encoded, equivalent to 32 bytes of zeros\nconst core = await sdk.get('hyper://yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy')\n\n// Don't auto-join the swarm for the core on init\nconst core = await sdk.get('example', {autoJoin: false})\n```\n\n### sdk.getDrive()\n\nYou can initialize a [Hyperdrive](https://github.com/holepunchto/hyperdrive-next) instance by passing in the same arguments as in `sdk.get()`.\n\nIn addition to the usual `hyperdrive` properties, there's a new `url` property to get the `hyper://` URL for the drive to used elsewhere.\n\nNote that the drives's metadata DB's discovery key will be used for replicating if `autoJoin` is `true`.\n\nHyperdrive is mostly useful for storing and loading files since it splits the metadata representing the file systema and the blob storage into separate cores.\n\n```JavaScript\nconst drive = await sdk.getDrive('hyper://blob.mauve.moe')\nfor(const path of drive.readdir('/')) {\n  const stat = drive.stat(path)\n}\n```\n\n### sdk.getBee()\n\nYou can initialize a [Hyperbee](https://github.com/holepunchto/hyperbee) instance by passing the same arguments as in `sdk.get()`.\n\nIn addition to the usual `hyperbee` properties, there's a new `url` property to get the `hyper://` URL for the bee to used elsewhere.\n\nAdditionally, you should pass in a `keyEncoding` and a `valueEncoding` in order to control the encoding for data that's being written.\n\nHyperbee is best used when you want to create database indexes.\n\nFor an out of the box database with a proper query language, check out [HyperbeeDeeBee](https://github.com/RangerMauve/hyperbeedeebee/).\n\n```JavaScript\nconst db = await sdk.getBee('example db')\n\nconst db = await sdk.getBee('example db', {keyEncoding: 'utf8', valueEncoding: 'json')\nawait db.put('hello', 'world')\n\nfor(const entry of db.createReadStream()) {\n  console.log(entry)\n}\n```\n\n### sdk.resolveDNSToKey()\n\nYou can manually resolve DNS addresses to hypercore keys on domains using the DNS Link spec with this method.\n\nHowever, it's not mandatory to use DNS since `sdk.get()` will automatically detect and perform resolutions of DNS for `hyper://` URLs.\n\nHyper-SDK currently bypasses the OS DNS resolver and uses DNS Over HTTPS. You can configure your own using the `dnsResolver` config option and any of the options [on this list](https://dnsprivacy.org/public_resolvers/#dns-over-https-doh). By default we use the one provided by [Mozilla](https://developers.cloudflare.com/1.1.1.1/commitment-to-privacy/privacy-policy/firefox/).\n\n```JavaScript\nconst key = await sdk.resolveDNSToKey('example.mauve.moe')\n```\n\n### sdk.namespace()\n\nGet back a namespaced [Corestore](https://github.com/hypercore-protocol/corestore/) instance which can be passed to things like Hyperdrive.\n\nNote that cores initialized with a namespaced corestore will not be auto-joined and you will need to call `sdk.join(core.discoveryKey)` on said cores.\n\n```JavaScript\nimport Hypderdrive from \"hyperdrive\"\n\nconst drive = new Hyperdrive(sdk.namespace('example'))\n\n// Wait for the drive to initiailize\nawait drive.ready()\n\n// Manually trigger peer lookup for this drive\nsdk.join(drive.publicKey)\n```\n\n### sdk.join() / sdk.leave()\n\nYou can manually trigger peer discovery of hypercores as well as stop peer discovery.\nThis can be done by using the `discoveryKey` of a hypercore, or any 32 byte buffer.\n\nAs well, you can use string names for topics in order to discover peers based on a human readable string.\nWhen using string topics, they are converted to 32 byte buffers using the [Hypercore Crypto namespace algorithm](https://github.com/mafintosh/hypercore-crypto#list--cryptonamespacename-count).\n\n```JavaScript\nconst core = await sdk.get('example', {autoJoin: false})\n\n// Start finding peers without advertising\nsdk.join(core.discoveryKey, {server: false})\n\n// Listen on a human readable topic\nsdk.join(\"cool cat videos\")\n\nsdk.leave(core.discoveryKey)\nsdk.leave(\"cool cat videos\")\n```\n\n### sdk.joinPeer() / sdk.leavePeer()\n\n```JavaScript\nconst sdk1 = await SDK.create({storage: './sdk1'})\nconst sdk2 = await SDK.create({storage: './sdk1'})\n\nsdk1.joinPeer(sdk2.publicKey)\n```\n\n### sdk.close()\n\nThis will gracefully close connections, remove advertisements from the DHT, and close any open file handles.\n\nMake sure you invoke this to keep the network fast and to avoid data corruption!\n","funding_links":[],"categories":["**Awesome Pears 🍐**","[🌐 decentralize](https://github.com/stars/ketsapiwiq/lists/decentralize)","JavaScript"],"sub_categories":["Building Blocks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRangerMauve%2Fhyper-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRangerMauve%2Fhyper-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRangerMauve%2Fhyper-sdk/lists"}