├── .github ├── dependabot.yml └── workflows │ └── test-and-release.yml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── example.js ├── hashmap.ipldsch ├── interface.ts ├── ipld-hashmap.js ├── package.json ├── schema-validate.js ├── test ├── basic-test.js ├── errors-test.js ├── nontrivial-test.js ├── spec-fixture.js └── words-fixture.js ├── tsconfig.json └── types ├── interface.d.ts ├── interface.d.ts.map ├── ipld-hashmap.d.ts ├── ipld-hashmap.d.ts.map ├── schema-validate.d.ts └── schema-validate.d.ts.map /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: 'github-actions' 4 | directory: '/' 5 | schedule: 6 | interval: 'daily' 7 | commit-message: 8 | prefix: 'chore' 9 | include: 'scope' 10 | - package-ecosystem: 'npm' 11 | directory: '/' 12 | schedule: 13 | interval: 'daily' 14 | commit-message: 15 | prefix: 'chore' 16 | include: 'scope' 17 | -------------------------------------------------------------------------------- /.github/workflows/test-and-release.yml: -------------------------------------------------------------------------------- 1 | name: Test & Maybe Release 2 | on: [push, pull_request] 3 | jobs: 4 | test: 5 | strategy: 6 | fail-fast: false 7 | matrix: 8 | node: [16.x, 18.x, current, lts/*] 9 | os: [macos-latest, ubuntu-latest] 10 | runs-on: ${{ matrix.os }} 11 | steps: 12 | - name: Checkout Repository 13 | uses: actions/checkout@v4 14 | - name: Use Node.js ${{ matrix.node }} 15 | uses: actions/setup-node@v4.0.1 16 | with: 17 | node-version: ${{ matrix.node }} 18 | - name: Install Dependencies 19 | run: | 20 | npm install --no-progress 21 | - name: Run tests 22 | run: | 23 | npm test 24 | test-windows: 25 | strategy: 26 | fail-fast: false 27 | matrix: 28 | node: [16.x, 18.x, current, lts/*] 29 | os: [windows-latest] 30 | runs-on: ${{ matrix.os }} 31 | steps: 32 | - name: Checkout Repository 33 | uses: actions/checkout@v4 34 | - name: Use Node.js ${{ matrix.node }} 35 | uses: actions/setup-node@v4.0.1 36 | with: 37 | node-version: ${{ matrix.node }} 38 | - name: Install Dependencies 39 | run: | 40 | npm install --no-progress 41 | - name: Run tests 42 | run: | 43 | npm run test:node 44 | release: 45 | name: Release 46 | needs: [test, test-windows] 47 | runs-on: ubuntu-latest 48 | if: github.event_name == 'push' && github.ref == 'refs/heads/master' 49 | steps: 50 | - name: Checkout 51 | uses: actions/checkout@v4 52 | with: 53 | fetch-depth: 0 54 | - name: Setup Node.js 55 | uses: actions/setup-node@v4.0.1 56 | with: 57 | node-version: lts/* 58 | - name: Install dependencies 59 | run: | 60 | npm install --no-progress --no-package-lock --no-save 61 | - name: Build 62 | run: | 63 | npm run build 64 | - name: Install plugins 65 | run: | 66 | npm install \ 67 | @semantic-release/commit-analyzer \ 68 | conventional-changelog-conventionalcommits \ 69 | @semantic-release/release-notes-generator \ 70 | @semantic-release/npm \ 71 | @semantic-release/github \ 72 | @semantic-release/git \ 73 | @semantic-release/changelog \ 74 | --no-progress --no-package-lock --no-save 75 | - name: Release 76 | env: 77 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 78 | NPM_TOKEN: ${{ secrets.NPM_TOKEN }} 79 | run: npx semantic-release 80 | 81 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .nyc_output/ 3 | coverage/ 4 | package-lock.json 5 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## [3.0.9](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.8...v3.0.9) (2024-01-11) 2 | 3 | 4 | ### Trivial Changes 5 | 6 | * **deps-dev:** bump chai from 4.3.10 to 5.0.0 ([ca5b24e](https://github.com/rvagg/js-ipld-hashmap/commit/ca5b24e8a169f8f48e9c82c4a9fda3817ccc9d7e)) 7 | 8 | ## [3.0.8](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.7...v3.0.8) (2024-01-11) 9 | 10 | 11 | ### Trivial Changes 12 | 13 | * **deps:** bump actions/setup-node from 4.0.0 to 4.0.1 ([770b07a](https://github.com/rvagg/js-ipld-hashmap/commit/770b07a3247e97d7f8a2c5fe4c701fba40f897be)) 14 | 15 | ## [3.0.7](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.6...v3.0.7) (2024-01-10) 16 | 17 | 18 | ### Trivial Changes 19 | 20 | * **deps:** bump iamap from 3.0.9 to 4.0.0 ([9dff179](https://github.com/rvagg/js-ipld-hashmap/commit/9dff179c56c5c85a76dec8ef4a551e0928562191)) 21 | 22 | ## [3.0.6](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.5...v3.0.6) (2024-01-10) 23 | 24 | 25 | ### Trivial Changes 26 | 27 | * **deps-dev:** bump c8 from 8.0.1 to 9.0.0 ([f440368](https://github.com/rvagg/js-ipld-hashmap/commit/f440368bc47d10eef59a17369a1070dfe15a02e5)) 28 | 29 | ## [3.0.5](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.4...v3.0.5) (2024-01-02) 30 | 31 | 32 | ### Trivial Changes 33 | 34 | * **deps:** bump multiformats from 12.1.3 to 13.0.0 ([d3d652c](https://github.com/rvagg/js-ipld-hashmap/commit/d3d652ce432e3697b768b24ceb232bee6804ae64)) 35 | 36 | ## [3.0.4](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.3...v3.0.4) (2023-10-25) 37 | 38 | 39 | ### Trivial Changes 40 | 41 | * **deps:** bump actions/checkout from 3 to 4 ([5fb648a](https://github.com/rvagg/js-ipld-hashmap/commit/5fb648ab93fc82f5b8f038fa5ab22037f9d938d3)) 42 | * **deps:** bump actions/setup-node from 3.8.1 to 4.0.0 ([7a9773e](https://github.com/rvagg/js-ipld-hashmap/commit/7a9773ee0a6f121653685d7a881cd4273e9ca114)) 43 | 44 | ## [3.0.3](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.2...v3.0.3) (2023-08-17) 45 | 46 | 47 | ### Trivial Changes 48 | 49 | * **deps:** bump actions/setup-node from 3.8.0 to 3.8.1 ([ae12297](https://github.com/rvagg/js-ipld-hashmap/commit/ae12297271cd69bca6e4f8b6ec1c040c6cdd85ac)) 50 | * **deps:** bump ipld-schema-describer from 2.0.1 to 3.0.2 ([9f61ed2](https://github.com/rvagg/js-ipld-hashmap/commit/9f61ed22501090e4f67cf1cc70716a2c267298ae)) 51 | 52 | ## [3.0.2](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.1...v3.0.2) (2023-08-15) 53 | 54 | 55 | ### Trivial Changes 56 | 57 | * **deps:** bump actions/setup-node from 3.6.0 to 3.8.0 ([477af69](https://github.com/rvagg/js-ipld-hashmap/commit/477af69d7f6ee4b3902f5990365f1b3b0445f3aa)) 58 | 59 | ## [3.0.1](https://github.com/rvagg/js-ipld-hashmap/compare/v3.0.0...v3.0.1) (2023-06-15) 60 | 61 | 62 | ### Trivial Changes 63 | 64 | * **deps:** bump multiformats from 11.0.2 to 12.0.0 ([8327f9c](https://github.com/rvagg/js-ipld-hashmap/commit/8327f9cf6f49f4ac6a2ee041be0d7b3ee90079ef)) 65 | 66 | ## [3.0.0](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.18...v3.0.0) (2023-06-14) 67 | 68 | 69 | ### ⚠ BREAKING CHANGES 70 | 71 | * drop Node.js 14.x support (#59) 72 | 73 | ### Trivial Changes 74 | 75 | * **deps-dev:** bump c8 from 7.14.0 to 8.0.0 ([4052ba2](https://github.com/rvagg/js-ipld-hashmap/commit/4052ba2cde89b868c50183c322cb40f4620f2c8e)) 76 | * **deps:** bump iamap from 2.0.17 to 3.0.1 ([de20235](https://github.com/rvagg/js-ipld-hashmap/commit/de20235e7fb3cd43b0fdbdb9ed2eb2efc854a8c7)) 77 | * drop Node.js 14.x support ([#59](https://github.com/rvagg/js-ipld-hashmap/issues/59)) ([55bc393](https://github.com/rvagg/js-ipld-hashmap/commit/55bc393f84d854d29a4139416c7190c3d60879c3)) 78 | 79 | ## [2.1.18](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.17...v2.1.18) (2023-03-31) 80 | 81 | 82 | ### Bug Fixes 83 | 84 | * **typescript:** optional bitWidth and bucketSize when loading ([#56](https://github.com/rvagg/js-ipld-hashmap/issues/56)) ([22c41cc](https://github.com/rvagg/js-ipld-hashmap/commit/22c41cc6fcb07aed54dc3b6dd6685a61ffaf99ea)) 85 | 86 | ## [2.1.17](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.16...v2.1.17) (2023-03-17) 87 | 88 | 89 | ### Trivial Changes 90 | 91 | * **deps-dev:** bump typescript from 4.9.5 to 5.0.2 ([5adc139](https://github.com/rvagg/js-ipld-hashmap/commit/5adc1392cd015aa4cf108a44bdbf6db7b8ee2428)) 92 | 93 | ## [2.1.16](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.15...v2.1.16) (2023-01-06) 94 | 95 | 96 | ### Bug Fixes 97 | 98 | * release with Node.js 18 ([95ec4c4](https://github.com/rvagg/js-ipld-hashmap/commit/95ec4c4df41ad22d7658e14d6f6c07dff0c6092c)) 99 | 100 | 101 | ### Trivial Changes 102 | 103 | * **deps-dev:** bump @ipld/dag-cbor from 8.0.1 to 9.0.0 ([cc5a507](https://github.com/rvagg/js-ipld-hashmap/commit/cc5a50711d2c8e23f6810bee09b418ca066b4248)) 104 | 105 | ## [2.1.15](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.14...v2.1.15) (2023-01-06) 106 | 107 | 108 | ### Trivial Changes 109 | 110 | * **deps:** bump actions/setup-node from 3.5.1 to 3.6.0 ([41c780b](https://github.com/rvagg/js-ipld-hashmap/commit/41c780ba4f2df84cb5ae669869538b7b0e1779a3)) 111 | 112 | ## [2.1.14](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.13...v2.1.14) (2023-01-03) 113 | 114 | 115 | ### Trivial Changes 116 | 117 | * **deps-dev:** bump @ipld/dag-cbor from 7.0.3 to 8.0.0 ([ea85213](https://github.com/rvagg/js-ipld-hashmap/commit/ea85213d4a9c70cb6b3b24e58b89611a280440d7)) 118 | * **deps:** bump multiformats from 10.0.3 to 11.0.0 ([af827c7](https://github.com/rvagg/js-ipld-hashmap/commit/af827c757c76ab4ede511ade913445196f04a80f)) 119 | * **no-release:** bump actions/setup-node from 3.5.0 to 3.5.1 ([#48](https://github.com/rvagg/js-ipld-hashmap/issues/48)) ([957f12b](https://github.com/rvagg/js-ipld-hashmap/commit/957f12b6d5d7bd1d1be486abed56a043d910a5c3)) 120 | 121 | ## [2.1.13](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.12...v2.1.13) (2022-10-13) 122 | 123 | 124 | ### Trivial Changes 125 | 126 | * **deps:** bump multiformats from 9.9.0 to 10.0.0 ([#47](https://github.com/rvagg/js-ipld-hashmap/issues/47)) ([8afa704](https://github.com/rvagg/js-ipld-hashmap/commit/8afa704f90bb90c559718f663016078db0d71a0f)) 127 | * **no-release:** bump @types/mocha from 9.1.1 to 10.0.0 ([#46](https://github.com/rvagg/js-ipld-hashmap/issues/46)) ([eb1b7cf](https://github.com/rvagg/js-ipld-hashmap/commit/eb1b7cf0dc225493b23c75774b886f60b9bf2df6)) 128 | * **no-release:** bump actions/setup-node from 3.4.1 to 3.5.0 ([#45](https://github.com/rvagg/js-ipld-hashmap/issues/45)) ([f22b5b8](https://github.com/rvagg/js-ipld-hashmap/commit/f22b5b8afeebe9a6d190369a44a6c7aec9dcff9b)) 129 | 130 | ## [2.1.12](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.11...v2.1.12) (2022-08-16) 131 | 132 | 133 | ### Bug Fixes 134 | 135 | * update for latest IPLD schema stack ([0304efb](https://github.com/rvagg/js-ipld-hashmap/commit/0304efba4ab1edf4641661d680fc27654ce97629)) 136 | 137 | 138 | ### Trivial Changes 139 | 140 | * **deps:** bump ipld-schema from 2.0.2 to 3.0.2 ([cabacdc](https://github.com/rvagg/js-ipld-hashmap/commit/cabacdcf0504785d3dc6802fd7de2ad0a61de6cb)) 141 | * **no-release:** bump actions/setup-node from 3.1.1 to 3.2.0 ([#39](https://github.com/rvagg/js-ipld-hashmap/issues/39)) ([b585f7c](https://github.com/rvagg/js-ipld-hashmap/commit/b585f7c362c3a9c059c18167c2c58d239080634c)) 142 | * **no-release:** bump actions/setup-node from 3.2.0 to 3.3.0 ([#40](https://github.com/rvagg/js-ipld-hashmap/issues/40)) ([e817a95](https://github.com/rvagg/js-ipld-hashmap/commit/e817a952ae3241432a9386d2c46b54fee7c45120)) 143 | * **no-release:** bump actions/setup-node from 3.3.0 to 3.4.0 ([#42](https://github.com/rvagg/js-ipld-hashmap/issues/42)) ([7007716](https://github.com/rvagg/js-ipld-hashmap/commit/7007716681861654a66fc935138b9f7f4b181206)) 144 | * **no-release:** bump actions/setup-node from 3.4.0 to 3.4.1 ([#43](https://github.com/rvagg/js-ipld-hashmap/issues/43)) ([a28ca9e](https://github.com/rvagg/js-ipld-hashmap/commit/a28ca9e2c112c5361f1539a44922952abbf4ea40)) 145 | 146 | ### [2.1.11](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.10...v2.1.11) (2022-05-03) 147 | 148 | 149 | ### Trivial Changes 150 | 151 | * **deps:** bump ipld-schema from 1.1.6 to 2.0.2 ([#37](https://github.com/rvagg/js-ipld-hashmap/issues/37)) ([4163a4b](https://github.com/rvagg/js-ipld-hashmap/commit/4163a4b8088af38d5f1b3fa2007407d8748c85b7)) 152 | * **no-release:** bump actions/checkout from 2.4.0 to 3 ([#29](https://github.com/rvagg/js-ipld-hashmap/issues/29)) ([e852cc9](https://github.com/rvagg/js-ipld-hashmap/commit/e852cc90e0e446b88e7adfe9440237ed852c6fa1)) 153 | * **no-release:** bump actions/setup-node from 2.5.1 to 3.0.0 ([#28](https://github.com/rvagg/js-ipld-hashmap/issues/28)) ([c10f1c5](https://github.com/rvagg/js-ipld-hashmap/commit/c10f1c5e3431b39fcaca93726c267e067c5e9d5c)) 154 | * **no-release:** bump actions/setup-node from 3.0.0 to 3.1.0 ([#33](https://github.com/rvagg/js-ipld-hashmap/issues/33)) ([a60107d](https://github.com/rvagg/js-ipld-hashmap/commit/a60107d69995933178a297d75ea007324aa63312)) 155 | * **no-release:** bump actions/setup-node from 3.1.0 to 3.1.1 ([#34](https://github.com/rvagg/js-ipld-hashmap/issues/34)) ([a6f9454](https://github.com/rvagg/js-ipld-hashmap/commit/a6f94544976ffa2c84e67092b9ec6c44b46c4306)) 156 | * **no-release:** bump mocha from 9.2.2 to 10.0.0 ([#36](https://github.com/rvagg/js-ipld-hashmap/issues/36)) ([944ac14](https://github.com/rvagg/js-ipld-hashmap/commit/944ac142f27134964ce4f04bc2b1de00d4787b94)) 157 | * **no-release:** bump polendina from 2.0.15 to 3.0.0 ([#38](https://github.com/rvagg/js-ipld-hashmap/issues/38)) ([38b30ed](https://github.com/rvagg/js-ipld-hashmap/commit/38b30ed3850364ede5813f546cf35a3174ce5b81)) 158 | * **no-release:** bump standard from 16.0.4 to 17.0.0 ([#35](https://github.com/rvagg/js-ipld-hashmap/issues/35)) ([010356f](https://github.com/rvagg/js-ipld-hashmap/commit/010356f31c21d240223c18bce5d05e4d9bb331db)) 159 | 160 | ### [2.1.10](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.9...v2.1.10) (2022-02-23) 161 | 162 | 163 | ### Trivial Changes 164 | 165 | * **doc:** minor typo in readme ([48dbab7](https://github.com/rvagg/js-ipld-hashmap/commit/48dbab784a2b845d12aedd4b0bb01ba922a2bd8e)) 166 | * **no-release:** bump @ipld/dag-cbor from 6.0.15 to 7.0.0 ([#25](https://github.com/rvagg/js-ipld-hashmap/issues/25)) ([a12cf80](https://github.com/rvagg/js-ipld-hashmap/commit/a12cf80bc9535ddf1451b7f01699e923558fa6ab)) 167 | * **no-release:** bump actions/setup-node from 2.5.0 to 2.5.1 ([#26](https://github.com/rvagg/js-ipld-hashmap/issues/26)) ([6629fc7](https://github.com/rvagg/js-ipld-hashmap/commit/6629fc7e9a027f4eee75afc6fe82f5be8757b7f5)) 168 | 169 | ### [2.1.9](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.8...v2.1.9) (2021-12-09) 170 | 171 | 172 | ### Trivial Changes 173 | 174 | * **deps-dev:** bump polendina from 1.1.1 to 2.0.0 ([#24](https://github.com/rvagg/js-ipld-hashmap/issues/24)) ([31fc577](https://github.com/rvagg/js-ipld-hashmap/commit/31fc577e989b134e534a8cc2cd7a944e4c93f764)) 175 | * **no-release:** bump actions/setup-node from 2.4.1 to 2.5.0 ([#23](https://github.com/rvagg/js-ipld-hashmap/issues/23)) ([81e51b1](https://github.com/rvagg/js-ipld-hashmap/commit/81e51b1f340be367a6df1a8481979be613af8a6f)) 176 | 177 | ### [2.1.8](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.7...v2.1.8) (2021-11-04) 178 | 179 | 180 | ### Trivial Changes 181 | 182 | * **deps:** bump actions/checkout from 2.3.5 to 2.4.0 ([cc6790e](https://github.com/rvagg/js-ipld-hashmap/commit/cc6790e2a31d2acd3b5d4f1bde866b9250b14404)) 183 | 184 | ### [2.1.7](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.6...v2.1.7) (2021-10-18) 185 | 186 | 187 | ### Trivial Changes 188 | 189 | * **deps:** bump actions/checkout from 2.3.4 to 2.3.5 ([217bb45](https://github.com/rvagg/js-ipld-hashmap/commit/217bb45de4088d1b779b8114205f6f7b59d9065f)) 190 | 191 | ### [2.1.6](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.5...v2.1.6) (2021-09-28) 192 | 193 | 194 | ### Trivial Changes 195 | 196 | * **deps:** bump actions/setup-node from 2.4.0 to 2.4.1 ([21b3d5f](https://github.com/rvagg/js-ipld-hashmap/commit/21b3d5fdce3337249c3325b42739692c2c1f1580)) 197 | 198 | ### [2.1.5](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.4...v2.1.5) (2021-08-07) 199 | 200 | 201 | ### Trivial Changes 202 | 203 | * **deps:** bump actions/setup-node from 2.3.2 to 2.4.0 ([90e787d](https://github.com/rvagg/js-ipld-hashmap/commit/90e787d6fc68765f00b9c9cf5851a93558d97432)) 204 | 205 | ### [2.1.4](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.3...v2.1.4) (2021-08-05) 206 | 207 | 208 | ### Trivial Changes 209 | 210 | * **deps:** bump actions/setup-node from 2.3.0 to 2.3.2 ([113f2ca](https://github.com/rvagg/js-ipld-hashmap/commit/113f2cadb69ce9e3ae05afd7a2d47e8ee8384713)) 211 | 212 | ### [2.1.3](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.2...v2.1.3) (2021-07-23) 213 | 214 | 215 | ### Trivial Changes 216 | 217 | * **deps-dev:** bump @types/mocha from 8.2.3 to 9.0.0 ([ab39aee](https://github.com/rvagg/js-ipld-hashmap/commit/ab39aeefa8afd66f746f9c96e3dee16a9091eae6)) 218 | 219 | ### [2.1.2](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.1...v2.1.2) (2021-07-20) 220 | 221 | 222 | ### Trivial Changes 223 | 224 | * **deps:** bump actions/setup-node from 2.2.0 to 2.3.0 ([37c315f](https://github.com/rvagg/js-ipld-hashmap/commit/37c315f08c426331fdb7531f0604f834aa054a03)) 225 | 226 | ### [2.1.1](https://github.com/rvagg/js-ipld-hashmap/compare/v2.1.0...v2.1.1) (2021-07-09) 227 | 228 | 229 | ### Bug Fixes 230 | 231 | * AsyncIterator -> AsyncIterable ([22f4481](https://github.com/rvagg/js-ipld-hashmap/commit/22f44815bb230d56d72a71957c99b6ae03c1b6ac)) 232 | 233 | ## [2.1.0](https://github.com/rvagg/js-ipld-hashmap/compare/v2.0.2...v2.1.0) (2021-07-09) 234 | 235 | 236 | ### Features 237 | 238 | * expose ability to interact with keys as bytes ([df722e8](https://github.com/rvagg/js-ipld-hashmap/commit/df722e88614d1add98a1ff7cc3a05b82cd19dada)) 239 | 240 | ### [2.0.2](https://github.com/rvagg/js-ipld-hashmap/compare/v2.0.1...v2.0.2) (2021-07-09) 241 | 242 | 243 | ### Bug Fixes 244 | 245 | * optional hasher and hashBytes params in types defn ([c27113c](https://github.com/rvagg/js-ipld-hashmap/commit/c27113ce904d3f85a9c79e3c4db0e0ea4e19190c)) 246 | 247 | ### [2.0.1](https://github.com/rvagg/js-ipld-hashmap/compare/v2.0.0...v2.0.1) (2021-07-07) 248 | 249 | 250 | ### Trivial Changes 251 | 252 | * **deps:** bump actions/setup-node from 2.1.5 to 2.2.0 ([3a9c93f](https://github.com/rvagg/js-ipld-hashmap/commit/3a9c93f384ecb45d95ea23da1253b10c5a3abb9d)) 253 | 254 | ## [2.0.0](https://github.com/rvagg/js-ipld-hashmap/compare/v1.0.0...v2.0.0) (2021-07-07) 255 | 256 | 257 | ### ⚠ BREAKING CHANGES 258 | 259 | * adapt to new iamap serialization format 260 | * use multiformats, mandatory hasher & codec, latest iamap 261 | 262 | ### Features 263 | 264 | * adapt to new iamap serialization format ([6d07159](https://github.com/rvagg/js-ipld-hashmap/commit/6d07159e89ba8e5fa7da1648ab9fbcfc33ab5c2f)) 265 | * full typing, ESM, remove murmur, browser tests, and more ([1dcb258](https://github.com/rvagg/js-ipld-hashmap/commit/1dcb25813daee6e260a2cbc6f5884ae8edd09706)) 266 | * use multiformats, mandatory hasher & codec, latest iamap ([4ae611d](https://github.com/rvagg/js-ipld-hashmap/commit/4ae611d6537e57f26f292a4318e3d3102e6e4aaf)) 267 | 268 | 269 | ### Bug Fixes 270 | 271 | * properly handle bitWidth and bucketSize options ([8811fcd](https://github.com/rvagg/js-ipld-hashmap/commit/8811fcd4384a980e758a846c3cd89ce2a402513e)) 272 | 273 | 274 | ### Trivial Changes 275 | 276 | * add alice-words spec fixture generator / checker ([5490d77](https://github.com/rvagg/js-ipld-hashmap/commit/5490d770ae4473673582c8ae1b4df732f218d72b)) 277 | * add example, expand and clarify README ([36e286b](https://github.com/rvagg/js-ipld-hashmap/commit/36e286b055e1d4e465d5485661a2c171845619e3)) 278 | * add GitHub Actions - dependabot, test & semantic-release ([b312521](https://github.com/rvagg/js-ipld-hashmap/commit/b312521130ea6636209b9601606eec6ce38e4fbd)) 279 | * add schema and compiled validator ([84501ce](https://github.com/rvagg/js-ipld-hashmap/commit/84501cedd4aa4b07ecc1631e944752bbc032e10d)) 280 | * update deps ([64751bb](https://github.com/rvagg/js-ipld-hashmap/commit/64751bb1de2bc67b2d29da7dd988e08ca5b7eb3a)) 281 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2019 Rod Vagg 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"); 4 | you may not use this file except in compliance with the License. 5 | You may obtain a copy of the License at 6 | 7 | http://www.apache.org/licenses/LICENSE-2.0 8 | 9 | Unless required by applicable law or agreed to in writing, software 10 | distributed under the License is distributed on an "AS IS" BASIS, 11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | See the License for the specific language governing permissions and 13 | limitations under the License. 14 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # js-ipld-hashmap 2 | 3 | **An associative array Map-type data structure for very large, distributed data sets built on [IPLD](http://ipld.io/).** 4 | [![NPM](https://nodei.co/npm/ipld-hashmap.svg)](https://nodei.co/npm/ipld-hashmap/) 5 | 6 | This JavaScript implementation conforms to the [IPLD HashMap specification](https://github.com/ipld/specs/blob/master/schema-layer/data-structures/hashmap.md) which describes a HAMT algorithm for constructing an evenly distributed associative array of arbitrary size using content addressed blocks. 7 | 8 | * [Example](#example) 9 | * [Description](#description) 10 | * [API](#api) 11 | * [License and Copyright](#license-and-copyright) 12 | 13 | ## Example 14 | 15 | ```js 16 | import fs from 'fs/promises' 17 | import { create, load } from 'ipld-hashmap' 18 | import { sha256 as blockHasher } from 'multiformats/hashes/sha2' 19 | import * as blockCodec from '@ipld/dag-cbor' // encode blocks using the DAG-CBOR format 20 | 21 | // A basic in-memory store for mapping CIDs to their encoded Uint8Array blocks 22 | const store = { 23 | map: new Map(), 24 | get (k) { return store.map.get(k.toString()) }, 25 | put (k, v) { store.map.set(k.toString(), v) } 26 | } 27 | 28 | // Create a new HashMap by reading the package.json in the current directory and 29 | // storing an entry for each top level and second level field. 30 | async function setup () { 31 | const map = await create(store, { bitWidth: 4, bucketSize: 2, blockHasher, blockCodec }) 32 | const pkg = JSON.parse(await fs.readFile('./package.json')) 33 | for (const [key, value] of Object.entries(pkg)) { 34 | await map.set(key, value) 35 | if (typeof value === 'object') { 36 | for (const [key2, value2] of Object.entries(value)) { 37 | await map.set(`${key} -> ${key2}`, value2) 38 | } 39 | } 40 | } 41 | // return the CID of the root of the HashMap 42 | return map.cid 43 | } 44 | 45 | // given only the CID of the root of the HashMap, load it and print its contents 46 | async function dump (rootCid) { 47 | const map = await load(store, rootCid, { blockHasher, blockCodec }) 48 | console.log('ENTRIES ===========================') 49 | for await (const [key, value] of map.entries()) { 50 | console.log(`[${key}]:`, value) 51 | } 52 | console.log('STATS =============================') 53 | console.log('size:', await map.size()) 54 | console.log('blocks:') 55 | for await (const cid of map.cids()) { 56 | console.log('\t', cid, cid.equals(map.cid) ? '(ROOT)' : '') 57 | // console.dir(blockCodec.decode(store.get(cid)), { depth: Infinity }) 58 | } 59 | } 60 | 61 | setup() 62 | .then((root) => dump(root)) 63 | .catch((err) => { 64 | console.error(err) 65 | process.exit(1) 66 | }) 67 | ``` 68 | 69 | ## Description 70 | 71 | The `HashMap` in this implementation has an API similar to JavaScript's native [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object but uses asynchronous accessors rather than synchronous. When creating a new `HashMap` or loading one with existing data, a backing store must be provided. The backing store is provided via a `loader` interface which should have a `get()` method that returns binary IPLD block data when provided a [CID](https://github.com/multiformats/js-multiformats) (content identifier) and a `put()` method that takes both a CID and binary block data that will store the IPLD block. This interface may connect to a P2P network, or a block storage system that can load and save keyed by CID. 72 | 73 | The algorithm for this HashMap is implemented in [IAMap](https://github.com/rvagg/iamap), you can read more about it there, or in the [IPLD HashMap specification](https://github.com/ipld/specs/blob/master/schema-layer/data-structures/hashmap.md). IAMap is serialization and storage agnostic and therefore does not contain any IPLD dependencies. IAMap is also immutable, where each mutation operation returns a _new_ instance. 74 | 75 | This implementation wraps IAMap with IPLD primitives, including the use of CIDs and the standard [IPLD block encoding](https://github.com/multiformats/js-multiformats) formats and presents a mutable interface. Each `HashMap` object has its own root CID in the `cid` property. Whenever the `HashMap` is mutated (`get()` and `delete()`), the `cid` property will change to the new root block CID. 76 | 77 | You can create a new, empty, `HashMap` with [`async HashMap.create(loader[, options])`](#HashMap__create). Loading a `HashMap` from existing data can be done with [`async HashMap.create(loader[, root][, options])`](#HashMap__create). 78 | 79 | Be aware that each mutation operation will create at least one new block, stored via `loader.put()`. Large numbers of mutations will create many extraneous intermediate blocks which will need to be garbage collected from the backing store if the intermediate states are not required. 80 | 81 | ## API 82 | 83 | ### Contents 84 | 85 | * [`class HashMap`](#HashMap) 86 | * [`async HashMap#get(key)`](#HashMap_get) 87 | * [`async HashMap#has(key)`](#HashMap_has) 88 | * [`async HashMap#size()`](#HashMap_size) 89 | * [`async HashMap#set(key, value)`](#HashMap_set) 90 | * [`async HashMap#delete(key)`](#HashMap_delete) 91 | * [`async HashMap#values()`](#HashMap_values) 92 | * [`async HashMap#keys()`](#HashMap_keys) 93 | * [`async HashMap#keysRaw()`](#HashMap_keysRaw) 94 | * [`async * HashMapImpl#entries()`](#HashMapImpl_entries) 95 | * [`async * HashMapImpl#entriesRaw()`](#HashMapImpl_entriesRaw) 96 | * [`async HashMap#cids()`](#HashMap_cids) 97 | * [`async HashMapImpl.create(loader, options)`](#HashMapImpl__create) 98 | * [`async HashMapImpl.load(loader, root, options)`](#HashMapImpl__load) 99 | 100 | 101 | ### `class HashMap` 102 | 103 | An IPLD HashMap object. Create a new HashMap or load an existing one with the asynchronous 104 | [`HashMap.create`](#HashMap__create) factory method. 105 | 106 | This class serves mostly as a IPLD usability wrapper for 107 | [IAMap](https://github.com/rvagg/iamap) which implements the majority of the logic behind the 108 | IPLD HashMap specification, without being IPLD-specific. IAMap is immutable, in that each 109 | mutation (delete or set) returns a new IAMap instance. `HashMap`, however, is immutable, and 110 | mutation operations may be performed on the same object but its `cid` property will change 111 | with mutations. 112 | 113 | If consumed with TypeScript typings, `HashMap` is generic over value template type `V`, where various 114 | operations will accept or return template type `V`. 115 | 116 | Properties: 117 | 118 | * `cid` `(CID)`: The _current_ CID of this HashMap. It is important to note that this CID 119 | will change when successfully performing mutation operations [`HashMap#set`](#HashMap_set) or 120 | [`HashMap#delete`](#HashMap_delete). Where a [`HashMap#set`](#HashMap_set) does not change an existing value (because 121 | a key already exists with that value) or [`HashMap#delete`](#HashMap_delete) does not delete an existing 122 | key/value pair (because it doesn't already exist in this HashMap), the `cid` will not change. 123 | 124 | 125 | ### `async HashMap#get(key)` 126 | 127 | * `key` `(string|Uint8Array)`: The key of the key/value pair entry to look up in this HashMap. 128 | 129 | * Returns: `Promise<(V|undefined)>`: The value (of template type `V`) stored for the given `key` which may be any type serializable 130 | by IPLD, or a CID to an existing IPLD object. This should match what was provided by 131 | [`HashMap#set`](#HashMap_set) as the `value` for this `key`. If the `key` is not stored in this HashMap, 132 | `undefined` will be returned. 133 | 134 | Fetches the value of the provided `key` stored in this HashMap, if it exists. 135 | 136 | 137 | ### `async HashMap#has(key)` 138 | 139 | * `key` `(string|Uint8Array)`: The key of the key/value pair entry to look up in this HashMap. 140 | 141 | * Returns: `Promise`: `true` if the `key` exists in this HashMap, `false` otherwise. 142 | 143 | Check whether the provided `key` exists in this HashMap. The equivalent of performing 144 | `map.get(key) !== undefined`. 145 | 146 | 147 | ### `async HashMap#size()` 148 | 149 | * Returns: `Promise`: An integer greater than or equal to zero indicating the number of key/value pairs stored 150 | in this HashMap. 151 | 152 | Count the number of key/value pairs stored in this HashMap. 153 | 154 | 155 | ### `async HashMap#set(key, value)` 156 | 157 | * `key` `(string|Uint8Array)`: The key of the new key/value pair entry to store in this HashMap. 158 | * `value` `(V)`: The value (of template type `V`) to store, either an object that can be 159 | serialized inline via IPLD or a CID pointing to another object. 160 | 161 | * Returns: `Promise` 162 | 163 | Add a key/value pair to this HashMap. The value may be any object that can be serialized by 164 | IPLD, or a CID to a more complex (or larger) object. [`HashMap#get`](#HashMap_get) operations on the 165 | same `key` will retreve the `value` as it was set as long as serialization and deserialization 166 | results in the same object. 167 | 168 | If the `key` already exists in this HashMap, the existing entry will have the `value` replaced 169 | with the new one provided. If the `value` is the same, the HashMap will remain unchanged. 170 | 171 | As a mutation operation, performing a successful `set()` where a new key/value pair or new 172 | `value` for a given `key` is set, a new root node will be generated so `map.cid` will be a 173 | different CID. This CID should be used to refer to this collection in the backing store where 174 | persistence is required. 175 | 176 | 177 | ### `async HashMap#delete(key)` 178 | 179 | * `key` `(string|Uint8Array)`: The key of the key/value pair entry to remove from this HashMap. 180 | 181 | * Returns: `Promise` 182 | 183 | Remove a key/value pair to this HashMap. 184 | 185 | If the `key` exists in this HashMap, its entry will be entirely removed. If the `key` does not 186 | exist in this HashMap, no changes will occur. 187 | 188 | As a mutation operation, performing a successful `delete()` where an existing key/value pair 189 | is removed from the collection, a new root node will be generated so `map.cid` will be a 190 | different CID. This CID should be used to refer to this collection in the backing store where 191 | persistence is required. 192 | 193 | 194 | ### `async HashMap#values()` 195 | 196 | * Returns: `AsyncIterator`: An async iterator that yields values (of template type `V`) of the type stored in this 197 | collection, either inlined objects or CIDs. 198 | 199 | Asynchronously emit all values that exist within this HashMap collection. 200 | 201 | This will cause a full traversal of all nodes that make up this collection so may result in 202 | many block loads from the backing store if the collection is large. 203 | 204 | 205 | ### `async HashMap#keys()` 206 | 207 | * Returns: `AsyncIterator`: An async iterator that yields string keys stored in this collection. 208 | 209 | Asynchronously emit all keys that exist within this HashMap collection **as strings** rather 210 | than the stored bytes. 211 | 212 | This will cause a full traversal of all nodes that make up this 213 | collection so may result in many block loads from the backing store if the collection is large. 214 | 215 | 216 | ### `async HashMap#keysRaw()` 217 | 218 | * Returns: `AsyncIterator`: An async iterator that yields string keys stored in this collection. 219 | 220 | Asynchronously emit all keys that exist within this HashMap collection **as their raw bytes** 221 | rather than being converted to a string. 222 | 223 | This will cause a full traversal of all nodes that make up this collection so may result in 224 | many block loads from the backing store if the collection is large. 225 | 226 | 227 | ### `async * HashMapImpl#entries()` 228 | 229 | 230 | ### `async * HashMapImpl#entriesRaw()` 231 | 232 | 233 | ### `async HashMap#cids()` 234 | 235 | * Returns: `AsyncIterator`: An async iterator that yields CIDs for the blocks that comprise this HashMap. 236 | 237 | Asynchronously emit all CIDs for blocks that make up this HashMap. 238 | 239 | This will cause a full traversal of all nodes that make up this collection so may result in 240 | many block loads from the backing store if the collection is large. 241 | 242 | 243 | ### `async HashMapImpl.create(loader, options)` 244 | 245 | * `loader` `(Loader)`: A loader with `get(cid):block` and `put(cid, block)` functions for 246 | loading an storing block data by CID. 247 | * `options` `(CreateOptions)`: Options for the HashMap. Defaults are provided but you can tweak 248 | behavior according to your needs with these options. 249 | 250 | * Returns: `Promise>`: - A HashMap instance, either loaded from an existing root block CID, or a new, 251 | empty HashMap if no CID is provided. 252 | 253 | Create a new [`HashMap`](#HashMap) instance, beginning empty, or loading from existing data in a 254 | backing store. 255 | 256 | A backing store must be provided to make use of a HashMap, an interface to the store is given 257 | through the mandatory `loader` parameter. The backing store stores IPLD blocks, referenced by 258 | CIDs. `loader` must have two functions: `get(cid)` which should return the raw bytes (`Buffer` 259 | or `Uint8Array`) of a block matching the given CID, and `put(cid, block)` that will store the 260 | provided raw bytes of a block (`block`) and store it with the associated CID. 261 | 262 | 263 | ### `async HashMapImpl.load(loader, root, options)` 264 | 265 | * `loader` `(Loader)` 266 | * `root` `(CID)`: A root of an existing HashMap. Provide a CID if you want to load existing 267 | data. 268 | * `options` `(CreateOptions)` 269 | 270 | * Returns: `Promise>` 271 | 272 | ## License and Copyright 273 | 274 | Copyright 2019 Rod Vagg 275 | 276 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 277 | 278 | Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 279 | -------------------------------------------------------------------------------- /example.js: -------------------------------------------------------------------------------- 1 | import fs from 'fs/promises' 2 | import { create, load } from './ipld-hashmap.js' 3 | import { sha256 as blockHasher } from 'multiformats/hashes/sha2' 4 | import * as blockCodec from '@ipld/dag-cbor' // encode blocks using the DAG-CBOR format 5 | 6 | // A basic in-memory store for mapping CIDs to their encoded Uint8Array blocks 7 | const store = { 8 | map: new Map(), 9 | get (k) { return store.map.get(k.toString()) }, 10 | put (k, v) { store.map.set(k.toString(), v) } 11 | } 12 | 13 | // Create a new HashMap by reading the package.json in the current directory and 14 | // storing an entry for each top level and second level field. 15 | async function setup () { 16 | const map = await create(store, { bitWidth: 4, bucketSize: 2, blockHasher, blockCodec }) 17 | const pkg = JSON.parse(await fs.readFile('./package.json')) 18 | for (const [key, value] of Object.entries(pkg)) { 19 | await map.set(key, value) 20 | if (typeof value === 'object') { 21 | for (const [key2, value2] of Object.entries(value)) { 22 | await map.set(`${key} -> ${key2}`, value2) 23 | } 24 | } 25 | } 26 | // return the CID of the root of the HashMap 27 | return map.cid 28 | } 29 | 30 | // given only the CID of the root of the HashMap, load it and print its contents 31 | async function dump (rootCid) { 32 | const map = await load(store, rootCid, { blockHasher, blockCodec }) 33 | console.log('ENTRIES ===========================') 34 | for await (const [key, value] of map.entries()) { 35 | console.log(`[${key}]:`, value) 36 | } 37 | console.log('STATS =============================') 38 | console.log('size:', await map.size()) 39 | console.log('blocks:') 40 | for await (const cid of map.cids()) { 41 | console.log('\t', cid, cid.equals(map.cid) ? '(ROOT)' : '') 42 | // console.dir(blockCodec.decode(store.get(cid)), { depth: Infinity }) 43 | } 44 | } 45 | 46 | setup() 47 | .then((root) => dump(root)) 48 | .catch((err) => { 49 | console.error(err) 50 | process.exit(1) 51 | }) 52 | -------------------------------------------------------------------------------- /hashmap.ipldsch: -------------------------------------------------------------------------------- 1 | # Root node layout 2 | type HashMapRoot struct { 3 | hashAlg Int 4 | bucketSize Int 5 | hamt HashMapNode 6 | } 7 | 8 | # Non-root node layout 9 | type HashMapNode struct { 10 | map Bytes 11 | data [ Element ] 12 | } representation tuple 13 | 14 | type Element union { 15 | | &HashMapNode link 16 | | Bucket list 17 | } representation kinded 18 | 19 | type Bucket [ BucketEntry ] 20 | 21 | type BucketEntry struct { 22 | key Bytes 23 | value Any 24 | } representation tuple 25 | -------------------------------------------------------------------------------- /interface.ts: -------------------------------------------------------------------------------- 1 | import { CID } from 'multiformats/cid' 2 | import { BlockCodec } from 'multiformats/codecs/interface' 3 | import { MultihashHasher } from 'multiformats/hashes/interface' 4 | 5 | export interface HashMap { 6 | readonly cid: CID 7 | 8 | get (key: string | Uint8Array): Promise 9 | 10 | has (key: string | Uint8Array): Promise 11 | 12 | size (): Promise 13 | 14 | set (key: string | Uint8Array, value: V): Promise 15 | 16 | delete (key: string | Uint8Array): Promise 17 | 18 | values (): AsyncIterable 19 | 20 | keys (): AsyncIterable 21 | 22 | keysRaw (): AsyncIterable 23 | 24 | entries (): AsyncIterable<[string, V]> 25 | 26 | entriesRaw (): AsyncIterable<[Uint8Array, V]> 27 | 28 | cids (): AsyncIterable 29 | } 30 | 31 | export interface CreateOptions { 32 | blockCodec: BlockCodec 33 | 34 | blockHasher: MultihashHasher 35 | 36 | hasher?: MultihashHasher 37 | 38 | hashBytes?: number 39 | 40 | bitWidth?: number 41 | 42 | bucketSize?: number 43 | } 44 | 45 | export interface Loader { 46 | get (cid: CID): Promise 47 | put (cid: CID, bytes: Uint8Array): Promise 48 | } 49 | -------------------------------------------------------------------------------- /ipld-hashmap.js: -------------------------------------------------------------------------------- 1 | import { create as createIAMap, load as loadIAMap, registerHasher } from 'iamap' 2 | import { CID } from 'multiformats/cid' 3 | import * as Block from 'multiformats/block' 4 | import { sha256 } from 'multiformats/hashes/sha2' 5 | import { HashMapRoot as validateHashMapRoot, HashMapNode as validateHashMapNode } from './schema-validate.js' 6 | import { describe } from 'ipld-schema-describer' 7 | // @ts-ignore 8 | import { print as schemaPrint } from 'ipld-schema/print.js' 9 | 10 | const DEFAULT_HASHER = sha256 11 | const DEFAULT_HASH_BYTES = 32 12 | // 5/3 seems to offer best perf characteristics in terms of raw speed 13 | // (Filecoin found this too for their HAMT usage) 14 | // but amount and size of garbage will change with different parameters 15 | const DEFAULT_BITWIDTH = 5 16 | const DEFAULT_BUCKET_SIZE = 3 17 | 18 | const textDecoder = new TextDecoder() 19 | 20 | /** 21 | * @template V 22 | * @typedef {import('iamap').IAMap} IAMap 23 | */ 24 | /** 25 | * @template V 26 | * @typedef {import('iamap').Store} Store 27 | */ 28 | /** 29 | * @typedef {import('multiformats/hashes/interface').MultihashHasher} MultihashHasher 30 | */ 31 | /** 32 | * @template V 33 | * @typedef {import('./interface').HashMap} HashMap 34 | */ 35 | /** 36 | * @template {number} Codec 37 | * @template V 38 | * @typedef {import('./interface').CreateOptions} CreateOptions 39 | */ 40 | /** 41 | * @typedef {import('./interface').Loader} Loader 42 | */ 43 | 44 | /** 45 | * @classdesc 46 | * An IPLD HashMap object. Create a new HashMap or load an existing one with the asynchronous 47 | * {@link HashMap.create} factory method. 48 | * 49 | * This class serves mostly as a IPLD usability wrapper for 50 | * [IAMap](https://github.com/rvagg/iamap) which implements the majority of the logic behind the 51 | * IPLD HashMap specification, without being IPLD-specific. IAMap is immutable, in that each 52 | * mutation (delete or set) returns a new IAMap instance. `HashMap`, however, is immutable, and 53 | * mutation operations may be performed on the same object but its `cid` property will change 54 | * with mutations. 55 | * 56 | * If consumed with TypeScript typings, `HashMap` is generic over value template type `V`, where various 57 | * operations will accept or return template type `V`. 58 | * 59 | * @name HashMap 60 | * @template V 61 | * @implements {HashMap} 62 | * @class 63 | * @hideconstructor 64 | * @property {CID} cid - The _current_ CID of this HashMap. It is important to note that this CID 65 | * will change when successfully performing mutation operations `set()` or 66 | * `delete()`. Where a `set()` does not change an existing value (because 67 | * a key already exists with that value) or `delete()` does not delete an existing 68 | * key/value pair (because it doesn't already exist in this HashMap), the `cid` will not change. 69 | */ 70 | class HashMapImpl { 71 | /** 72 | * @ignore 73 | * @param {IAMap} iamap 74 | */ 75 | constructor (iamap) { 76 | // IAMap is immutable, so mutation operations return a new instance so 77 | // we use `this._iamap` as the _current_ instance and wrap around that, 78 | // switching it out as we mutate 79 | this._iamap = iamap 80 | } 81 | 82 | /** 83 | * @name HashMap#get 84 | * @description 85 | * Fetches the value of the provided `key` stored in this HashMap, if it exists. 86 | * @function 87 | * @async 88 | * @memberof HashMap 89 | * @param {string|Uint8Array} key - The key of the key/value pair entry to look up in this HashMap. 90 | * @return {Promise} 91 | * The value (of template type `V`) stored for the given `key` which may be any type serializable 92 | * by IPLD, or a CID to an existing IPLD object. This should match what was provided by 93 | * {@link HashMap#set} as the `value` for this `key`. If the `key` is not stored in this HashMap, 94 | * `undefined` will be returned. 95 | */ 96 | async get (key) { 97 | return this._iamap.get(key) 98 | } 99 | 100 | /** 101 | * @name HashMap#has 102 | * @description 103 | * Check whether the provided `key` exists in this HashMap. The equivalent of performing 104 | * `map.get(key) !== undefined`. 105 | * @function 106 | * @async 107 | * @memberof HashMap 108 | * @param {string|Uint8Array} key - The key of the key/value pair entry to look up in this HashMap. 109 | * @return {Promise} 110 | * `true` if the `key` exists in this HashMap, `false` otherwise. 111 | */ 112 | async has (key) { 113 | return this._iamap.has(key) 114 | } 115 | 116 | /** 117 | * @name HashMap#size 118 | * @description 119 | * Count the number of key/value pairs stored in this HashMap. 120 | * @function 121 | * @async 122 | * @memberof HashMap 123 | * @return {Promise} 124 | * An integer greater than or equal to zero indicating the number of key/value pairse stored 125 | * in this HashMap. 126 | */ 127 | async size () { 128 | return this._iamap.size() 129 | } 130 | 131 | /** 132 | * @name HashMap#set 133 | * @description 134 | * Add a key/value pair to this HashMap. The value may be any object that can be serialized by 135 | * IPLD, or a CID to a more complex (or larger) object. {@link HashMap#get} operations on the 136 | * same `key` will retreve the `value` as it was set as long as serialization and deserialization 137 | * results in the same object. 138 | * 139 | * If the `key` already exists in this HashMap, the existing entry will have the `value` replaced 140 | * with the new one provided. If the `value` is the same, the HashMap will remain unchanged. 141 | * 142 | * As a mutation operation, performing a successful `set()` where a new key/value pair or new 143 | * `value` for a given `key` is set, a new root node will be generated so `map.cid` will be a 144 | * different CID. This CID should be used to refer to this collection in the backing store where 145 | * persistence is required. 146 | * @function 147 | * @async 148 | * @memberof HashMap 149 | * @param {string|Uint8Array} key - The key of the new key/value pair entry to store in this HashMap. 150 | * @param {V} value - The value (of template type `V`) to store, either an object that can be 151 | * serialized inline via IPLD or a CID pointing to another object. 152 | * @returns {Promise} 153 | */ 154 | async set (key, value) { 155 | this._iamap = await this._iamap.set(key, value) 156 | } 157 | 158 | /** 159 | * @name HashMap#delete 160 | * @description 161 | * Remove a key/value pair to this HashMap. 162 | * 163 | * If the `key` exists in this HashMap, its entry will be entirely removed. If the `key` does not 164 | * exist in this HashMap, no changes will occur. 165 | * 166 | * As a mutation operation, performing a successful `delete()` where an existing key/value pair 167 | * is removed from the collection, a new root node will be generated so `map.cid` will be a 168 | * different CID. This CID should be used to refer to this collection in the backing store where 169 | * persistence is required. 170 | * @function 171 | * @async 172 | * @memberof HashMap 173 | * @param {string|Uint8Array} key - The key of the key/value pair entry to remove from this HashMap. 174 | * @returns {Promise} 175 | */ 176 | async delete (key) { 177 | this._iamap = await this._iamap.delete(key) 178 | } 179 | 180 | /** 181 | * @name HashMap#values 182 | * @description 183 | * Asynchronously emit all values that exist within this HashMap collection. 184 | * 185 | * This will cause a full traversal of all nodes that make up this collection so may result in 186 | * many block loads from the backing store if the collection is large. 187 | * @function 188 | * @async 189 | * @returns {AsyncIterable} 190 | * An async iterator that yields values (of template type `V`) of the type stored in this 191 | * collection, either inlined objects or CIDs. 192 | */ 193 | async * values () { 194 | yield * this._iamap.values() 195 | } 196 | 197 | /** 198 | * @name HashMap#keys 199 | * @description 200 | * Asynchronously emit all keys that exist within this HashMap collection **as strings** rather 201 | * than the stored bytes. 202 | * 203 | * This will cause a full traversal of all nodes that make up this 204 | * collection so may result in many block loads from the backing store if the collection is large. 205 | * @function 206 | * @async 207 | * @returns {AsyncIterable} 208 | * An async iterator that yields string keys stored in this collection. 209 | */ 210 | async * keys () { 211 | for await (const key of this._iamap.keys()) { 212 | // IAMap keys are Uint8Arrays, make them strings 213 | yield textDecoder.decode(key) 214 | } 215 | } 216 | 217 | /** 218 | * @name HashMap#keysRaw 219 | * @description 220 | * Asynchronously emit all keys that exist within this HashMap collection **as their raw bytes** 221 | * rather than being converted to a string. 222 | * 223 | * This will cause a full traversal of all nodes that make up this collection so may result in 224 | * many block loads from the backing store if the collection is large. 225 | * @function 226 | * @async 227 | * @returns {AsyncIterable} 228 | * An async iterator that yields string keys stored in this collection. 229 | */ 230 | async * keysRaw () { 231 | yield * this._iamap.keys() 232 | } 233 | 234 | /** 235 | * @name HashMap#entries 236 | * @description 237 | * Asynchronously emit all key/value pairs that exist within this HashMap collection. Keys will be 238 | * given **as strings** rather than their raw byte form as stored. 239 | * 240 | * This will cause a full traversal of all nodes that make up this collection so may result in 241 | * many block loads from the backing store if the collection is large. 242 | * 243 | * Entries are returned in tuple form like 244 | * [Map#entries()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries), 245 | * an array of key/value pairs where element `0` is the key and `1` is the value. 246 | * @function 247 | * @async 248 | * @returns {AsyncIterable<[string, V]>} 249 | * An async iterator that yields key/value pair tuples. 250 | */ 251 | async * entries () { 252 | for await (const { key, value } of this._iamap.entries()) { 253 | // IAMap keys are Uint8Arrays, make them strings 254 | yield [textDecoder.decode(key), value] 255 | } 256 | } 257 | 258 | /** 259 | * @name HashMap#entriesRaw 260 | * @description 261 | * Asynchronously emit all key/value pairs that exist within this HashMap collection. Keys will be 262 | * given **as raw bytes** as stored rather than being converted to strings. 263 | * 264 | * This will cause a full traversal of all nodes that make up this collection so may result in 265 | * many block loads from the backing store if the collection is large. 266 | * 267 | * Entries are returned in tuple form like 268 | * [Map#entries()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries), 269 | * an array of key/value pairs where element `0` is the key and `1` is the value. 270 | * @function 271 | * @async 272 | * @returns {AsyncIterable<[Uint8Array, V]>} 273 | * An async iterator that yields key/value pair tuples. 274 | */ 275 | async * entriesRaw () { 276 | for await (const { key, value } of this._iamap.entries()) { 277 | yield [key, value] 278 | } 279 | } 280 | 281 | /** 282 | * @name HashMap#cids 283 | * @description 284 | * Asynchronously emit all CIDs for blocks that make up this HashMap. 285 | * 286 | * This will cause a full traversal of all nodes that make up this collection so may result in 287 | * many block loads from the backing store if the collection is large. 288 | * @function 289 | * @async 290 | * @returns {AsyncIterable} 291 | * An async iterator that yields CIDs for the blocks that comprise this HashMap. 292 | */ 293 | async * cids () { 294 | yield * this._iamap.ids() 295 | } 296 | 297 | get cid () { 298 | return this._iamap.id 299 | } 300 | 301 | /** 302 | * Create a new {@link HashMap} instance, beginning empty, or loading from existing data in a 303 | * backing store. 304 | * 305 | * A backing store must be provided to make use of a HashMap, an interface to the store is given 306 | * through the mandatory `loader` parameter. The backing store stores IPLD blocks, referenced by 307 | * CIDs. `loader` must have two functions: `get(cid)` which should return the raw bytes (`Buffer` 308 | * or `Uint8Array`) of a block matching the given CID, and `put(cid, block)` that will store the 309 | * provided raw bytes of a block (`block`) and store it with the associated CID. 310 | * 311 | * @async 312 | * @template V 313 | * @template {number} Codec 314 | * @param {Loader} loader - A loader with `get(cid):block` and `put(cid, block)` functions for 315 | * loading an storing block data by CID. 316 | * @param {CreateOptions} options - Options for the HashMap. Defaults are provided but you can tweak 317 | * behavior according to your needs with these options. 318 | * @return {Promise>} - A HashMap instance, either loaded from an existing root block CID, or a new, 319 | * empty HashMap if no CID is provided. 320 | */ 321 | static async create (loader, options) { 322 | return _load(loader, null, options) 323 | } 324 | 325 | /** 326 | * @template V 327 | * @template {number} Codec 328 | * @param {Loader} loader 329 | * @param {CID} root - A root of an existing HashMap. Provide a CID if you want to load existing 330 | * data. 331 | * @param {CreateOptions} options 332 | * @returns {Promise>} 333 | */ 334 | static async load (loader, root, options) { 335 | return _load(loader, root, options) 336 | } 337 | } 338 | 339 | /** 340 | * @ignore 341 | * @template V 342 | * @template {number} Codec 343 | * @param {Loader} loader 344 | * @param {CID|null} root 345 | * @param {CreateOptions} options 346 | * @returns {Promise>} 347 | */ 348 | export async function _load (loader, root, options) { 349 | const cid = CID.asCID(root) 350 | 351 | if (!loader || typeof loader.get !== 'function' || typeof loader.put !== 'function') { 352 | throw new TypeError('\'loader\' object with get() and put() methods is required') 353 | } 354 | 355 | if (typeof options !== 'object') { 356 | throw new TypeError('An \'options\' argument is required') 357 | } 358 | 359 | if (!('blockCodec' in options) || 360 | typeof options.blockCodec !== 'object' || 361 | typeof options.blockCodec.code !== 'number' || 362 | typeof options.blockCodec.encode !== 'function' || 363 | typeof options.blockCodec.decode !== 'function') { 364 | throw new TypeError('A valid \'blockCodec\' option is required') 365 | } 366 | const codec = options.blockCodec 367 | if (!('blockHasher' in options) || 368 | typeof options.blockHasher !== 'object' || 369 | typeof options.blockHasher.digest !== 'function' || 370 | typeof options.blockHasher.code !== 'number') { 371 | throw new TypeError('A valid \'blockHasher\' option is required') 372 | } 373 | const hasher = options.blockHasher 374 | 375 | /** 376 | * @ignore 377 | * @type {MultihashHasher} 378 | */ 379 | const hamtHasher = (() => { 380 | if ('hasher' in options) { 381 | if (typeof options.hasher !== 'object' || 382 | typeof options.hasher.digest !== 'function' || 383 | typeof options.hasher.code !== 'number') { 384 | throw new TypeError('\'hasher\' option must be a Multihasher') 385 | } 386 | return options.hasher 387 | } 388 | return DEFAULT_HASHER 389 | })() 390 | const hashBytes = (() => { 391 | if ('hashBytes' in options) { 392 | if (typeof options.hashBytes !== 'number') { 393 | throw new TypeError('\'hashBytes\' option must be a number') 394 | } 395 | /* c8 ignore next 2 */ 396 | return options.hashBytes 397 | } 398 | return DEFAULT_HASH_BYTES 399 | })() 400 | /** 401 | * @ignore 402 | * @param {Uint8Array} bytes 403 | */ 404 | const hashFn = async (bytes) => { 405 | const hash = await sha256.digest(bytes) 406 | return hash.digest 407 | } 408 | registerHasher(hamtHasher.code, hashBytes, hashFn) 409 | 410 | const bitWidth = (() => { 411 | if ('bitWidth' in options) { 412 | if (typeof options.bitWidth !== 'number') { 413 | throw new TypeError('\'bitWidth\' option must be a number') 414 | } 415 | return options.bitWidth 416 | } 417 | return DEFAULT_BITWIDTH 418 | })() 419 | 420 | const bucketSize = (() => { 421 | if ('bucketSize' in options) { 422 | if (typeof options.bucketSize !== 'number') { 423 | throw new TypeError('\'bucketSize\' option must be a number') 424 | } 425 | return options.bucketSize 426 | } 427 | return DEFAULT_BUCKET_SIZE 428 | })() 429 | 430 | const iamapOptions = { hashAlg: hamtHasher.code, bitWidth, bucketSize } 431 | 432 | const store = { 433 | /** 434 | * @ignore 435 | * @param {CID} cid 436 | * @returns {Promise} 437 | */ 438 | async load (cid) { 439 | const bytes = await loader.get(cid) 440 | if (!bytes) { 441 | throw new Error(`Could not load block for: ${cid}`) 442 | } 443 | // create() validates the block for us 444 | const block = await Block.create({ bytes, cid, hasher, codec }) 445 | validateBlock(block.value) 446 | return block.value 447 | }, 448 | 449 | /** 450 | * @ignore 451 | * @param {V} value 452 | * @returns {Promise} 453 | */ 454 | async save (value) { 455 | validateBlock(value) 456 | const block = await Block.encode({ value, codec, hasher }) 457 | await loader.put(block.cid, block.bytes) 458 | return block.cid 459 | }, 460 | 461 | /** 462 | * @ignore 463 | * @param {CID} cid1 464 | * @param {CID} cid2 465 | * @returns {boolean} 466 | */ 467 | isEqual (cid1, cid2) { 468 | return cid1.equals(cid2) 469 | }, 470 | 471 | /** 472 | * @ignore 473 | * @param {any} obj 474 | * @returns {boolean} 475 | */ 476 | isLink (obj) { 477 | return CID.asCID(obj) != null 478 | } 479 | } 480 | 481 | let iamap 482 | if (cid) { 483 | // load existing, ignoring bitWidth & bucketSize, they are loaded from the existing root 484 | iamap = await loadIAMap(store, cid) 485 | } else { 486 | // create new 487 | iamap = await createIAMap(store, iamapOptions) 488 | } 489 | 490 | return new HashMapImpl(iamap) 491 | } 492 | 493 | /** 494 | * @ignore 495 | * @param {any} block 496 | */ 497 | function validateBlock (block) { 498 | if (!validateHashMapNode(block) && !validateHashMapRoot(block)) { 499 | const description = schemaPrint(describe(block).schema) 500 | throw new Error(`Internal error: unexpected layout for HashMap block does not match schema, got:\n${description}`) 501 | } 502 | } 503 | 504 | export const create = HashMapImpl.create 505 | export const load = HashMapImpl.load 506 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "ipld-hashmap", 3 | "version": "3.0.9", 4 | "description": "A JavaScript implementation of the IPLD HashMap specification", 5 | "main": "ipld-hashmap.js", 6 | "type": "module", 7 | "scripts": { 8 | "lint": "standard", 9 | "test:node": "c8 --check-coverage --exclude schema-validate.js --exclude test/ --branches 100 --functions 100 --lines 100 mocha test/*-test.js", 10 | "test:browser": "polendina --page --worker --serviceworker --cleanup test/*-test.js", 11 | "test": "npm run lint && npm run build:types && npm run test:node && npm run test:browser", 12 | "coverage": "c8 --reporter=html mocha test/*-test.js && npm_config_yes=true npx st -d coverage -p 8080", 13 | "build": "npm run build:types", 14 | "build:types": "tsc --build", 15 | "docs": "jsdoc4readme --readme ipld-hashmap.js", 16 | "schema-validator": "npm_config_yes=true npx ipld-schema-validator to-js hashmap.ipldsch > schema-validate.js" 17 | }, 18 | "author": "Rod (http://r.va.gg/)", 19 | "license": "Apache-2.0", 20 | "dependencies": { 21 | "iamap": "^4.0.0", 22 | "ipld-schema": "^3.0.3", 23 | "ipld-schema-describer": "^3.0.6", 24 | "multiformats": "^13.0.1" 25 | }, 26 | "devDependencies": { 27 | "@ipld/dag-cbor": "^9.0.8", 28 | "@rvagg/chai-as-promised": "^8.0.1", 29 | "@types/chai": "^4.3.11", 30 | "@types/mocha": "^10.0.6", 31 | "c8": "^9.0.0", 32 | "chai": "^5.0.0", 33 | "jsdoc4readme": "^1.4.0", 34 | "mocha": "^10.2.0", 35 | "polendina": "^3.2.1", 36 | "standard": "^17.1.0", 37 | "typescript": "^5.3.3" 38 | }, 39 | "repository": { 40 | "type": "git", 41 | "url": "git://github.com/rvagg/js-ipld-hashmap.git" 42 | }, 43 | "typesVersions": { 44 | "*": { 45 | "*": [ 46 | "types/*" 47 | ], 48 | "types/*": [ 49 | "types/*" 50 | ] 51 | } 52 | }, 53 | "release": { 54 | "branches": [ 55 | "master" 56 | ], 57 | "plugins": [ 58 | [ 59 | "@semantic-release/commit-analyzer", 60 | { 61 | "preset": "conventionalcommits", 62 | "releaseRules": [ 63 | { 64 | "breaking": true, 65 | "release": "major" 66 | }, 67 | { 68 | "revert": true, 69 | "release": "patch" 70 | }, 71 | { 72 | "type": "feat", 73 | "release": "minor" 74 | }, 75 | { 76 | "type": "fix", 77 | "release": "patch" 78 | }, 79 | { 80 | "type": "chore", 81 | "release": "patch" 82 | }, 83 | { 84 | "type": "docs", 85 | "release": "patch" 86 | }, 87 | { 88 | "type": "test", 89 | "release": "patch" 90 | }, 91 | { 92 | "scope": "no-release", 93 | "release": false 94 | } 95 | ] 96 | } 97 | ], 98 | [ 99 | "@semantic-release/release-notes-generator", 100 | { 101 | "preset": "conventionalcommits", 102 | "presetConfig": { 103 | "types": [ 104 | { 105 | "type": "feat", 106 | "section": "Features" 107 | }, 108 | { 109 | "type": "fix", 110 | "section": "Bug Fixes" 111 | }, 112 | { 113 | "type": "chore", 114 | "section": "Trivial Changes" 115 | }, 116 | { 117 | "type": "docs", 118 | "section": "Trivial Changes" 119 | }, 120 | { 121 | "type": "test", 122 | "section": "Tests" 123 | } 124 | ] 125 | } 126 | } 127 | ], 128 | "@semantic-release/changelog", 129 | "@semantic-release/npm", 130 | "@semantic-release/github", 131 | "@semantic-release/git" 132 | ] 133 | } 134 | } 135 | -------------------------------------------------------------------------------- /schema-validate.js: -------------------------------------------------------------------------------- 1 | /** Auto-generated with ipld-schema-validator@1.0.1 at Tue Aug 16 2022 from IPLD Schema: 2 | * 3 | * # Root node layout 4 | * type HashMapRoot struct { 5 | * hashAlg Int 6 | * bucketSize Int 7 | * hamt HashMapNode 8 | * } 9 | * 10 | * # Non-root node layout 11 | * type HashMapNode struct { 12 | * map Bytes 13 | * data [ Element ] 14 | * } representation tuple 15 | * 16 | * type Element union { 17 | * | &HashMapNode link 18 | * | Bucket list 19 | * } representation kinded 20 | * 21 | * type Bucket [ BucketEntry ] 22 | * 23 | * type BucketEntry struct { 24 | * key Bytes 25 | * value Any 26 | * } representation tuple 27 | * 28 | */ 29 | 30 | const Kinds = { 31 | Null: /** @returns {boolean} */ (/** @type {any} */ obj) => obj === null, 32 | Int: /** @returns {boolean} */ (/** @type {any} */ obj) => Number.isInteger(obj), 33 | Float: /** @returns {boolean} */ (/** @type {any} */ obj) => typeof obj === 'number' && Number.isFinite(obj), 34 | String: /** @returns {boolean} */ (/** @type {any} */ obj) => typeof obj === 'string', 35 | Bool: /** @returns {boolean} */ (/** @type {any} */ obj) => typeof obj === 'boolean', 36 | Bytes: /** @returns {boolean} */ (/** @type {any} */ obj) => obj instanceof Uint8Array, 37 | Link: /** @returns {boolean} */ (/** @type {any} */ obj) => !Kinds.Null(obj) && typeof obj === 'object' && obj.asCID === obj, 38 | List: /** @returns {boolean} */ (/** @type {any} */ obj) => Array.isArray(obj), 39 | Map: /** @returns {boolean} */ (/** @type {any} */ obj) => !Kinds.Null(obj) && typeof obj === 'object' && obj.asCID !== obj && !Kinds.List(obj) && !Kinds.Bytes(obj) 40 | } 41 | /** @type {{ [k in string]: (obj:any)=>boolean}} */ 42 | const Types = { 43 | Int: Kinds.Int, 44 | 'HashMapRoot > hashAlg': /** @returns {boolean} */ (/** @type {any} */ obj) => Types.Int(obj), 45 | 'HashMapRoot > bucketSize': /** @returns {boolean} */ (/** @type {any} */ obj) => Types.Int(obj), 46 | Bytes: Kinds.Bytes, 47 | 'HashMapNode > map': /** @returns {boolean} */ (/** @type {any} */ obj) => Types.Bytes(obj), 48 | 'Element > HashMapNode (anon)': Kinds.Link, 49 | 'BucketEntry > key': /** @returns {boolean} */ (/** @type {any} */ obj) => Types.Bytes(obj), 50 | Any: /** @returns {boolean} */ (/** @type {any} */ obj) => (Kinds.Bool(obj) && Types.Bool(obj)) || (Kinds.String(obj) && Types.String(obj)) || (Kinds.Bytes(obj) && Types.Bytes(obj)) || (Kinds.Int(obj) && Types.Int(obj)) || (Kinds.Float(obj) && Types.Float(obj)) || (Kinds.Null(obj) && Types.Null(obj)) || (Kinds.Link(obj) && Types.Link(obj)) || (Kinds.Map(obj) && Types.AnyMap(obj)) || (Kinds.List(obj) && Types.AnyList(obj)), 51 | Bool: Kinds.Bool, 52 | String: Kinds.String, 53 | Float: Kinds.Float, 54 | Null: Kinds.Null, 55 | Link: Kinds.Link, 56 | AnyMap: /** @returns {boolean} */ (/** @type {any} */ obj) => Kinds.Map(obj) && Array.prototype.every.call(Object.values(obj), Types.Any), 57 | AnyList: /** @returns {boolean} */ (/** @type {any} */ obj) => Kinds.List(obj) && Array.prototype.every.call(obj, Types.Any), 58 | 'BucketEntry > value': /** @returns {boolean} */ (/** @type {any} */ obj) => Types.Any(obj), 59 | BucketEntry: /** @returns {boolean} */ (/** @type {any} */ obj) => Kinds.List(obj) && obj.length === 2 && Types['BucketEntry > key'](obj[0]) && Types['BucketEntry > value'](obj[1]), 60 | Bucket: /** @returns {boolean} */ (/** @type {any} */ obj) => Kinds.List(obj) && Array.prototype.every.call(obj, Types.BucketEntry), 61 | Element: /** @returns {boolean} */ (/** @type {any} */ obj) => (Kinds.Link(obj) && Types['Element > HashMapNode (anon)'](obj)) || (Kinds.List(obj) && Types.Bucket(obj)), 62 | 'HashMapNode > data (anon)': /** @returns {boolean} */ (/** @type {any} */ obj) => Kinds.List(obj) && Array.prototype.every.call(obj, Types.Element), 63 | 'HashMapNode > data': /** @returns {boolean} */ (/** @type {any} */ obj) => Types['HashMapNode > data (anon)'](obj), 64 | HashMapNode: /** @returns {boolean} */ (/** @type {any} */ obj) => Kinds.List(obj) && obj.length === 2 && Types['HashMapNode > map'](obj[0]) && Types['HashMapNode > data'](obj[1]), 65 | 'HashMapRoot > hamt': /** @returns {boolean} */ (/** @type {any} */ obj) => Types.HashMapNode(obj), 66 | HashMapRoot: /** @returns {boolean} */ (/** @type {any} */ obj) => { const keys = obj && Object.keys(obj); return Kinds.Map(obj) && ['hashAlg', 'bucketSize', 'hamt'].every((k) => keys.includes(k)) && Object.entries(obj).every(([name, value]) => Types['HashMapRoot > ' + name] && Types['HashMapRoot > ' + name](value)) } 67 | } 68 | 69 | export const HashMapRoot = Types.HashMapRoot 70 | export const HashMapNode = Types.HashMapNode 71 | export const Element = Types.Element 72 | export const Bucket = Types.Bucket 73 | export const BucketEntry = Types.BucketEntry 74 | -------------------------------------------------------------------------------- /test/basic-test.js: -------------------------------------------------------------------------------- 1 | /* eslint-env mocha */ 2 | 3 | import { create as createHashMap, load as loadHashMap } from '../ipld-hashmap.js' 4 | import { sha256 as blockHasher } from 'multiformats/hashes/sha2' 5 | import * as blockCodec from '@ipld/dag-cbor' 6 | import { assert } from 'chai' 7 | 8 | const textEncoder = new TextEncoder() 9 | 10 | async function toArray (asyncIterator) { 11 | const result = [] 12 | for await (const item of asyncIterator) { 13 | result.push(item) 14 | } 15 | return result 16 | } 17 | 18 | async function execute (options = {}) { 19 | const expectedEntries = 'foo:bar bar:baz baz:boom'.split(' ').map((e) => e.split(':')) 20 | 21 | const store = { 22 | map: new Map(), 23 | get (k) { return store.map.get(k.toString()) }, 24 | put (k, v) { store.map.set(k.toString(), v) } 25 | } 26 | 27 | const map = await createHashMap(store, Object.assign({ blockHasher, blockCodec }, options)) 28 | await map.set('foo', 'bar') 29 | await map.set('bar', 'baz') 30 | await map.set('baz', 'boom') 31 | 32 | await verify(map) // validate the map we just put things into 33 | 34 | const map2 = await loadHashMap(store, map.cid, { blockHasher, blockCodec }) 35 | 36 | assert.strictEqual(map2.cid, map.cid, 'CIDs match') 37 | 38 | await verify(map2) // validate a map we've loaded from the backing store 39 | 40 | await map2.delete('bar') 41 | expectedEntries.splice(1, 1) 42 | 43 | await verify(map2) 44 | 45 | const map3 = await loadHashMap(store, map2.cid, { blockHasher, blockCodec }) 46 | 47 | await verify(map3) 48 | 49 | async function verify (map) { 50 | const entries = await toArray(map.entries()) 51 | assert.sameDeepMembers(entries, expectedEntries, 'entries() returns expected list') 52 | 53 | const entriesRaw = await toArray(map.entriesRaw()) 54 | assert.sameDeepMembers( 55 | entriesRaw, 56 | expectedEntries.map((e) => [textEncoder.encode(e[0]), e[1]]), 57 | 'entriesRaw() returns expected list') 58 | 59 | const keys = await toArray(map.keys()) 60 | assert.sameDeepMembers(keys, expectedEntries.map((e) => e[0]), 'keys() returns expected list') 61 | 62 | const keysRaw = await toArray(map.keysRaw()) 63 | assert.sameDeepMembers( 64 | keysRaw, 65 | expectedEntries.map((e) => textEncoder.encode(e[0])), 66 | 'keysRaw() returns expected list') 67 | 68 | const values = await toArray(map.values()) 69 | assert.sameDeepMembers(values, expectedEntries.map((e) => e[1]), 'values() returns expected list') 70 | 71 | for (const [key, value] of expectedEntries) { 72 | assert.ok(await map.has(key)) 73 | assert.strictEqual(await map.get(key, value), value, `get(${key})`) 74 | } 75 | } 76 | } 77 | 78 | describe('Basics', () => { 79 | it('simple usage (defaults)', async () => { 80 | await execute() 81 | }) 82 | 83 | it('simple usage (bitWidth=8)', async () => { 84 | await execute({ bitWidth: 8 }) 85 | }) 86 | 87 | it('simple usage (bitWidth=4)', async () => { 88 | await execute({ bitWidth: 4 }) 89 | }) 90 | 91 | it('simple usage (bucketSize=2)', async () => { 92 | await execute({ bucketSize: 2 }) 93 | }) 94 | 95 | it('simple usage (bucketSize=5)', async () => { 96 | await execute({ bucketSize: 5 }) 97 | }) 98 | 99 | it('simple usage (bitWidth=8, bucketSize=5)', async () => { 100 | await execute({ bucketSize: 5, bitWidth: 8 }) 101 | }) 102 | }) 103 | -------------------------------------------------------------------------------- /test/errors-test.js: -------------------------------------------------------------------------------- 1 | /* eslint-env mocha */ 2 | 3 | import { create as createHashMap, load as loadHashMap } from '../ipld-hashmap.js' 4 | import { CID } from 'multiformats/cid' 5 | import { sha256 as blockHasher } from 'multiformats/hashes/sha2' 6 | import * as blockCodec from '@ipld/dag-cbor' 7 | import * as chai from 'chai' 8 | import chaiAsPromised from '@rvagg/chai-as-promised' 9 | 10 | chai.use(chaiAsPromised) 11 | const { assert } = chai 12 | 13 | describe('Errors', () => { 14 | it('create() errors', async () => { 15 | const dummyLoader = { get () {}, put () {} } 16 | await assert.isRejected(createHashMap(), '\'loader\' object with get() and put() methods is required') 17 | await assert.isRejected(createHashMap({}), '\'loader\' object with get() and put() methods is required') 18 | await assert.isRejected(createHashMap({ get: () => {} }), '\'loader\' object with get() and put() methods is required') 19 | await assert.isRejected(createHashMap(dummyLoader, 100), '\'options\' argument is required') 20 | await assert.isRejected(createHashMap(dummyLoader, { }), '\'blockCodec\' option') 21 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec: {} }), '\'blockCodec\' option') 22 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec: false }), '\'blockCodec\' option') 23 | const blockCodec = { code: 1, encode: () => {}, decode: () => {} } 24 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec }), '\'blockHasher\' option') 25 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher: false }), '\'blockHasher\' option') 26 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher: {} }), '\'blockHasher\' option') 27 | const blockHasher = { code: 2, digest: () => {} } 28 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher, hasher: false }), '\'hasher\' option') 29 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher, hasher: {} }), '\'hasher\' option') 30 | const hasher = blockHasher 31 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher, hasher, hashBytes: false }), '\'hashBytes\' option') 32 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher, bitWidth: 'nope' })) 33 | await assert.isRejected(createHashMap(dummyLoader, { blockCodec, blockHasher, bucketSize: 'nope' })) 34 | }) 35 | 36 | it('CID load mismatch', async () => { 37 | const store = { 38 | get () { 39 | return Uint8Array.from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]) // "random" bytes 40 | }, 41 | put () { } 42 | } 43 | 44 | const hash = await blockHasher.digest(new TextEncoder().encode('blorp')) 45 | const cid = CID.create(1, blockCodec.code, hash) // just a random CID 46 | await assert.isRejected(loadHashMap(store, cid, { blockCodec, blockHasher }), 'decode error') 47 | }) 48 | 49 | it('non-storing store', async () => { 50 | const store = { 51 | get () { }, 52 | put () { } 53 | } 54 | 55 | const hash = await blockHasher.digest(new TextEncoder().encode('blorp')) 56 | const cid = CID.create(1, blockCodec.code, hash) // just a random CID 57 | await assert.isRejected(loadHashMap(store, cid, { blockCodec, blockHasher })) // , 'bad loader rejects') 58 | }) 59 | 60 | it('bad serialization', async () => { 61 | const bytes = blockCodec.encode({ not: 'a', proper: 'hamt' }) 62 | const hash = await blockHasher.digest(bytes) 63 | const cid = CID.create(1, blockCodec.code, hash) 64 | 65 | const store = { 66 | get () { 67 | return bytes 68 | }, 69 | put () { } 70 | } 71 | 72 | await assert.isRejected(loadHashMap(store, cid, { blockCodec, blockHasher }), 'unexpected layout for HashMap block does not match schema') 73 | }) 74 | }) 75 | -------------------------------------------------------------------------------- /test/nontrivial-test.js: -------------------------------------------------------------------------------- 1 | /* eslint-env mocha */ 2 | 3 | import { create as createHashMap, load as loadHashMap } from '../ipld-hashmap.js' 4 | import { words } from './words-fixture.js' 5 | import { sha256 as blockHasher } from 'multiformats/hashes/sha2' 6 | import * as blockCodec from '@ipld/dag-cbor' 7 | import { assert } from 'chai' 8 | 9 | /** 10 | * @typedef {import('multiformats/cid').CID} CID 11 | */ 12 | 13 | describe('Nontrivial', () => { 14 | it('Tokenized file test', async () => { 15 | // index the words found in ipld-hashmap.js, storing an array of each instance's location 16 | const expectedMap = new Map() 17 | const store = { 18 | /** @type {Map} */ 19 | map: new Map(), 20 | /** @param {CID} k */ 21 | get (k) { 22 | return store.map.get(k.toString()) 23 | }, 24 | /** 25 | * @param {CID} k 26 | * @param {Uint8Array} v 27 | */ 28 | put (k, v) { 29 | store.map.set(k.toString(), v) 30 | } 31 | } 32 | const map = await createHashMap(store, { bitWidth: 5, blockHasher, blockCodec }) 33 | 34 | let line = 0 35 | let match 36 | while (line < words.length) { 37 | const wordsRe = /\w+/g 38 | while ((match = wordsRe.exec(words[line])) !== null) { 39 | const word = match[0] 40 | const column = wordsRe.lastIndex - word.length + 1 41 | const datum = { line, column } 42 | datum.line++ 43 | 44 | // store in our existing memory map 45 | if (!expectedMap.has(word)) { 46 | expectedMap.set(word, []) 47 | } 48 | expectedMap.get(word).push(datum) 49 | 50 | // store in the ipld map 51 | let results = await map.get(word) 52 | results = results ? results.slice() : [] // copy of results, or new 53 | results.push(datum) 54 | await map.set(word, results) 55 | } 56 | line++ 57 | } 58 | 59 | const actualMap = await loadHashMap(store, map.cid, { blockHasher, blockCodec }) 60 | 61 | assert.strictEqual(actualMap.cid, map.cid, 'CIDs match') 62 | 63 | // alice-words HashMap fixture expects this root 64 | assert.strictEqual(actualMap.cid.toString(), 65 | 'bafyreic672jz6huur4c2yekd3uycswe2xfqhjlmtmm5dorb6yoytgflova', 66 | 'CID matches spec fixture') 67 | 68 | assert.strictEqual(await actualMap.size(), expectedMap.size) 69 | for (const entry of expectedMap.entries()) { 70 | assert.deepStrictEqual([entry[0], await actualMap.get(entry[0])], entry) 71 | } 72 | 73 | let cidCount = 0 74 | let root 75 | for await (const cid of actualMap.cids()) { 76 | if (!root) { 77 | root = cid 78 | } 79 | cidCount++ 80 | } 81 | assert.ok(cidCount >= 30, `has at least 30 CIDs making up the collection (got ${cidCount})`) 82 | assert.strictEqual(actualMap.cid, root, 'first CID emitted is the root') 83 | 84 | // delete a word that doesn't exist and see that it hasn't mutated 85 | assert.strictEqual(await actualMap.has('polynomial'), false, 'doesn\'t have word it shouldn\'t') 86 | assert.strictEqual(await actualMap.get('polynomial'), undefined, 'doesn\'t have word it shouldn\'t') 87 | await actualMap.delete('polynomial') 88 | assert.strictEqual(await actualMap.has('polynomial'), false, 'doesn\'t have word it shouldn\'t') 89 | assert.strictEqual(await actualMap.get('polynomial'), undefined, 'doesn\'t have word it shouldn\'t') 90 | assert(actualMap.cid.equals(map.cid), 'CIDs still match') 91 | 92 | // delete one and test that deletion sticks 93 | await actualMap.delete('Alice') 94 | assert.strictEqual(await actualMap.has('Alice'), false, 'doesn\'t have what we deleted') 95 | assert.strictEqual(await actualMap.get('Alice'), undefined, 'doesn\'t have what we deleted') 96 | assert(!actualMap.cid.equals(map.cid), 'CIDs no longer match') 97 | }).timeout(1000 * 10) 98 | }) 99 | -------------------------------------------------------------------------------- /test/spec-fixture.js: -------------------------------------------------------------------------------- 1 | /* eslint-env mocha */ 2 | 3 | import { create as createHashMap, load as loadHashMap } from '../ipld-hashmap.js' 4 | import { words } from './words-fixture.js' 5 | import { sha256 as blockHasher } from 'multiformats/hashes/sha2' 6 | import * as blockCodec from '@ipld/dag-cbor' 7 | import { assert } from 'chai' 8 | import { CarWriter } from '@ipld/car/writer' 9 | import { CarBlockIterator } from '@ipld/car/iterator' 10 | import fs from 'fs' 11 | import { Readable } from 'stream' 12 | 13 | /** 14 | * @typedef {import('multiformats/cid').CID} CID 15 | */ 16 | 17 | function makeStore () { 18 | const store = { 19 | /** @type {Map} */ 20 | map: new Map(), 21 | /** @param {CID} k */ 22 | get (k) { 23 | return store.map.get(k.toString()) 24 | }, 25 | /** 26 | * @param {CID} k 27 | * @param {Uint8Array} v 28 | */ 29 | put (k, v) { 30 | store.map.set(k.toString(), v) 31 | } 32 | } 33 | return store 34 | } 35 | 36 | async function parseWords (cb) { 37 | let line = 0 38 | let match 39 | while (line < words.length) { 40 | const wordsRe = /\w+/g 41 | while ((match = wordsRe.exec(words[line])) !== null) { 42 | const word = match[0] 43 | const column = wordsRe.lastIndex - word.length + 1 44 | const datum = { line, column } 45 | datum.line++ 46 | await cb(word, datum) 47 | } 48 | line++ 49 | } 50 | } 51 | 52 | async function verifyMap (actualMap, expectedCid, expectedMap) { 53 | assert(actualMap.cid.equals(expectedCid), 'CIDs match') 54 | 55 | assert.strictEqual(await actualMap.size(), expectedMap.size) 56 | for (const entry of expectedMap.entries()) { 57 | assert.deepStrictEqual([entry[0], await actualMap.get(entry[0])], entry) 58 | } 59 | 60 | let cidCount = 0 61 | let root 62 | for await (const cid of actualMap.cids()) { 63 | if (!root) { 64 | root = cid 65 | } 66 | cidCount++ 67 | } 68 | assert.ok(cidCount >= 30, `has at least 30 CIDs making up the collection (got ${cidCount})`) 69 | assert(actualMap.cid.equals(root), 'first CID emitted is the root') 70 | 71 | // delete a word that doesn't exist and see that it hasn't mutated 72 | assert.strictEqual(await actualMap.has('polynomial'), false, 'doesn\'t have word it shouldn\'t') 73 | assert.strictEqual(await actualMap.get('polynomial'), undefined, 'doesn\'t have word it shouldn\'t') 74 | await actualMap.delete('polynomial') 75 | assert.strictEqual(await actualMap.has('polynomial'), false, 'doesn\'t have word it shouldn\'t') 76 | assert.strictEqual(await actualMap.get('polynomial'), undefined, 'doesn\'t have word it shouldn\'t') 77 | assert(actualMap.cid.equals(expectedCid), 'CIDs still match') 78 | 79 | // delete one and test that deletion sticks 80 | await actualMap.delete('Alice') 81 | assert.strictEqual(await actualMap.has('Alice'), false, 'doesn\'t have what we deleted') 82 | assert.strictEqual(await actualMap.get('Alice'), undefined, 'doesn\'t have what we deleted') 83 | assert(!actualMap.cid.equals(expectedCid), 'CIDs no longer match') 84 | } 85 | 86 | const runCreate = async () => { 87 | // index the words found in ipld-hashmap.js, storing an array of each instance's location 88 | const expectedMap = new Map() 89 | const store = makeStore() 90 | const map = await createHashMap(store, { bitWidth: 5, blockHasher, blockCodec }) 91 | 92 | await parseWords(async (word, datum) => { 93 | // store in our existing memory map 94 | if (!expectedMap.has(word)) { 95 | expectedMap.set(word, []) 96 | } 97 | expectedMap.get(word).push(datum) 98 | 99 | // store in the ipld map 100 | let results = await map.get(word) 101 | results = results ? results.slice() : [] // copy of results, or new 102 | results.push(datum) 103 | await map.set(word, results) 104 | }) 105 | 106 | const actualMap = await loadHashMap(store, map.cid, { blockHasher, blockCodec }) 107 | await verifyMap(actualMap, map.cid, expectedMap) 108 | 109 | const { writer, out } = await CarWriter.create([map.cid]) 110 | Readable.from(out).pipe(fs.createWriteStream('hamt.car')) 111 | 112 | for await (const cid of map.cids()) { 113 | const bytes = store.get(cid) 114 | if (!bytes) throw new Error('nope: ' + cid) 115 | await writer.put({ cid, bytes }) 116 | } 117 | await writer.close() 118 | 119 | console.log(`wrote ${map.cid} to hamt.car`) 120 | } 121 | 122 | const runLoad = async () => { 123 | const inStream = fs.createReadStream('hamt.car') 124 | const reader = await CarBlockIterator.fromIterable(inStream) 125 | const root = (await reader.getRoots())[0] 126 | const store = makeStore() 127 | for await (const { cid, bytes } of reader) { 128 | store.put(cid, bytes) 129 | } 130 | const actualMap = await loadHashMap(store, root, { blockHasher, blockCodec }) 131 | console.log(`loaded ${root} from hamt.car`) 132 | const expectedMap = new Map() 133 | await parseWords(async (word, datum) => { 134 | // store in our existing memory map 135 | if (!expectedMap.has(word)) { 136 | expectedMap.set(word, []) 137 | } 138 | expectedMap.get(word).push(datum) 139 | }) 140 | const obj = {} 141 | const keys = [...expectedMap.keys()] 142 | keys.sort() 143 | for (const key of keys) { 144 | // console.log(key, value) 145 | obj[key] = expectedMap.get(key) 146 | } 147 | await verifyMap(actualMap, root, expectedMap) 148 | console.log(JSON.stringify(obj, null, 2)) 149 | } 150 | 151 | // runCreate to generate the fixture 152 | runCreate().catch((err) => { 153 | console.error(err) 154 | process.exit(1) 155 | }).then(() => { 156 | // runLoad to load and verify the fixture -- run this alone without generating to check against spec 157 | runLoad().catch((err) => { 158 | console.error(err) 159 | process.exit(1) 160 | }) 161 | }) 162 | -------------------------------------------------------------------------------- /test/words-fixture.js: -------------------------------------------------------------------------------- 1 | export const words = ` 2 | Alice was beginning to get very tired of sitting by her sister on the bank, and of having nothing to do: once or twice she had peeped into the book her sister was reading, but it had no pictures or conversations in it, “and what is the use of a book,” thought Alice “without pictures or conversations?” 3 | So she was considering in her own mind (as well as she could, for the hot day made her feel very sleepy and stupid), whether the pleasure of making a daisy-chain would be worth the trouble of getting up and picking the daisies, when suddenly a White Rabbit with pink eyes ran close by her. 4 | There was nothing so very remarkable in that; nor did Alice think it so very much out of the way to hear the Rabbit say to itself, “Oh dear! Oh dear! I shall be late!” (when she thought it over afterwards, it occurred to her that she ought to have wondered at this, but at the time it all seemed quite natural); but when the Rabbit actually took a watch out of its waistcoat-pocket, and looked at it, and then hurried on, Alice started to her feet, for it flashed across her mind that she had never before seen a rabbit with either a waistcoat-pocket, or a watch to take out of it, and burning with curiosity, she ran across the field after it, and fortunately was just in time to see it pop down a large rabbit-hole under the hedge. 5 | In another moment down went Alice after it, never once considering how in the world she was to get out again. 6 | The rabbit-hole went straight on like a tunnel for some way, and then dipped suddenly down, so suddenly that Alice had not a moment to think about stopping herself before she found herself falling down a very deep well. 7 | Either the well was very deep, or she fell very slowly, for she had plenty of time as she went down to look about her and to wonder what was going to happen next. First, she tried to look down and make out what she was coming to, but it was too dark to see anything; then she looked at the sides of the well, and noticed that they were filled with cupboards and book-shelves; here and there she saw maps and pictures hung upon pegs. She took down a jar from one of the shelves as she passed; it was labelled “ORANGE MARMALADE”, but to her great disappointment it was empty: she did not like to drop the jar for fear of killing somebody underneath, so managed to put it into one of the cupboards as she fell past it. 8 | “Well!” thought Alice to herself, “after such a fall as this, I shall think nothing of tumbling down stairs! How brave they’ll all think me at home! Why, I wouldn’t say anything about it, even if I fell off the top of the house!” (Which was very likely true.) 9 | Down, down, down. Would the fall never come to an end? “I wonder how many miles I’ve fallen by this time?” she said aloud. “I must be getting somewhere near the centre of the earth. Let me see: that would be four thousand miles down, I think—” (for, you see, Alice had learnt several things of this sort in her lessons in the schoolroom, and though this was not a very good opportunity for showing off her knowledge, as there was no one to listen to her, still it was good practice to say it over) “—yes, that’s about the right distance—but then I wonder what Latitude or Longitude I’ve got to?” (Alice had no idea what Latitude was, or Longitude either, but thought they were nice grand words to say.) 10 | Presently she began again. “I wonder if I shall fall right through the earth! How funny it’ll seem to come out among the people that walk with their heads downward! The Antipathies, I think—” (she was rather glad there was no one listening, this time, as it didn’t sound at all the right word) “—but I shall have to ask them what the name of the country is, you know. Please, Ma’am, is this New Zealand or Australia?” (and she tried to curtsey as she spoke—fancy curtseying as you’re falling through the air! Do you think you could manage it?) “And what an ignorant little girl she’ll think me for asking! No, it’ll never do to ask: perhaps I shall see it written up somewhere.” 11 | Down, down, down. There was nothing else to do, so Alice soon began talking again. “Dinah’ll miss me very much to-night, I should think!” (Dinah was the cat.) “I hope they’ll remember her saucer of milk at tea-time. Dinah my dear! I wish you were down here with me! There are no mice in the air, I’m afraid, but you might catch a bat, and that’s very like a mouse, you know. But do cats eat bats, I wonder?” And here Alice began to get rather sleepy, and went on saying to herself, in a dreamy sort of way, “Do cats eat bats? Do cats eat bats?” and sometimes, “Do bats eat cats?” for, you see, as she couldn’t answer either question, it didn’t much matter which way she put it. She felt that she was dozing off, and had just begun to dream that she was walking hand in hand with Dinah, and saying to her very earnestly, “Now, Dinah, tell me the truth: did you ever eat a bat?” when suddenly, thump! thump! down she came upon a heap of sticks and dry leaves, and the fall was over. 12 | Alice was not a bit hurt, and she jumped up on to her feet in a moment: she looked up, but it was all dark overhead; before her was another long passage, and the White Rabbit was still in sight, hurrying down it. There was not a moment to be lost: away went Alice like the wind, and was just in time to hear it say, as it turned a corner, “Oh my ears and whiskers, how late it’s getting!” She was close behind it when she turned the corner, but the Rabbit was no longer to be seen: she found herself in a long, low hall, which was lit up by a row of lamps hanging from the roof. 13 | There were doors all round the hall, but they were all locked; and when Alice had been all the way down one side and up the other, trying every door, she walked sadly down the middle, wondering how she was ever to get out again. 14 | Suddenly she came upon a little three-legged table, all made of solid glass; there was nothing on it except a tiny golden key, and Alice’s first thought was that it might belong to one of the doors of the hall; but, alas! either the locks were too large, or the key was too small, but at any rate it would not open any of them. However, on the second time round, she came upon a low curtain she had not noticed before, and behind it was a little door about fifteen inches high: she tried the little golden key in the lock, and to her great delight it fitted! 15 | Alice opened the door and found that it led into a small passage, not much larger than a rat-hole: she knelt down and looked along the passage into the loveliest garden you ever saw. How she longed to get out of that dark hall, and wander about among those beds of bright flowers and those cool fountains, but she could not even get her head through the doorway; “and even if my head would go through,” thought poor Alice, “it would be of very little use without my shoulders. Oh, how I wish I could shut up like a telescope! I think I could, if I only knew how to begin.” For, you see, so many out-of-the-way things had happened lately, that Alice had begun to think that very few things indeed were really impossible. 16 | There seemed to be no use in waiting by the little door, so she went back to the table, half hoping she might find another key on it, or at any rate a book of rules for shutting people up like telescopes: this time she found a little bottle on it, (“which certainly was not here before,” said Alice,) and round the neck of the bottle was a paper label, with the words “DRINK ME,” beautifully printed on it in large letters. 17 | It was all very well to say “Drink me,” but the wise little Alice was not going to do that in a hurry. “No, I’ll look first,” she said, “and see whether it’s marked ‘poison’ or not”; for she had read several nice little histories about children who had got burnt, and eaten up by wild beasts and other unpleasant things, all because they would not remember the simple rules their friends had taught them: such as, that a red-hot poker will burn you if you hold it too long; and that if you cut your finger very deeply with a knife, it usually bleeds; and she had never forgotten that, if you drink much from a bottle marked “poison,” it is almost certain to disagree with you, sooner or later. 18 | However, this bottle was not marked “poison,” so Alice ventured to taste it, and finding it very nice, (it had, in fact, a sort of mixed flavour of cherry-tart, custard, pine-apple, roast turkey, toffee, and hot buttered toast,) she very soon finished it off. 19 | “What a curious feeling!” said Alice; “I must be shutting up like a telescope.” 20 | And so it was indeed: she was now only ten inches high, and her face brightened up at the thought that she was now the right size for going through the little door into that lovely garden. First, however, she waited for a few minutes to see if she was going to shrink any further: she felt a little nervous about this; “for it might end, you know,” said Alice to herself, “in my going out altogether, like a candle. I wonder what I should be like then?” And she tried to fancy what the flame of a candle is like after the candle is blown out, for she could not remember ever having seen such a thing. 21 | After a while, finding that nothing more happened, she decided on going into the garden at once; but, alas for poor Alice! when she got to the door, she found she had forgotten the little golden key, and when she went back to the table for it, she found she could not possibly reach it: she could see it quite plainly through the glass, and she tried her best to climb up one of the legs of the table, but it was too slippery; and when she had tired herself out with trying, the poor little thing sat down and cried. 22 | “Come, there’s no use in crying like that!” said Alice to herself, rather sharply; “I advise you to leave off this minute!” She generally gave herself very good advice, (though she very seldom followed it), and sometimes she scolded herself so severely as to bring tears into her eyes; and once she remembered trying to box her own ears for having cheated herself in a game of croquet she was playing against herself, for this curious child was very fond of pretending to be two people. “But it’s no use now,” thought poor Alice, “to pretend to be two people! Why, there’s hardly enough of me left to make one respectable person!” 23 | Soon her eye fell on a little glass box that was lying under the table: she opened it, and found in it a very small cake, on which the words “EAT ME” were beautifully marked in currants. “Well, I’ll eat it,” said Alice, “and if it makes me grow larger, I can reach the key; and if it makes me grow smaller, I can creep under the door; so either way I’ll get into the garden, and I don’t care which happens!” 24 | She ate a little bit, and said anxiously to herself, “Which way? Which way?”, holding her hand on the top of her head to feel which way it was growing, and she was quite surprised to find that she remained the same size: to be sure, this generally happens when one eats cake, but Alice had got so much into the way of expecting nothing but out-of-the-way things to happen, that it seemed quite dull and stupid for life to go on in the common way. 25 | So she set to work, and very soon finished off the cake. 26 | `.split('\n') 27 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "allowJs": true, 4 | "checkJs": true, 5 | "forceConsistentCasingInFileNames": true, 6 | "noImplicitReturns": false, 7 | "noImplicitAny": true, 8 | "noImplicitThis": true, 9 | "noFallthroughCasesInSwitch": true, 10 | "noUnusedLocals": true, 11 | "noUnusedParameters": true, 12 | "strictFunctionTypes": false, 13 | "strictNullChecks": true, 14 | "strictPropertyInitialization": true, 15 | "strictBindCallApply": true, 16 | "strict": true, 17 | "alwaysStrict": true, 18 | "esModuleInterop": true, 19 | "target": "ES2018", 20 | "module": "ESNext", 21 | "moduleResolution": "node", 22 | "declaration": true, 23 | "declarationMap": true, 24 | "outDir": "types", 25 | "skipLibCheck": true, 26 | "stripInternal": true, 27 | "resolveJsonModule": true, 28 | "emitDeclarationOnly": true, 29 | "baseUrl": "." 30 | }, 31 | "exclude": [ 32 | "node_modules", 33 | "types", 34 | "test", 35 | "example.js" 36 | ], 37 | "compileOnSave": false 38 | } 39 | -------------------------------------------------------------------------------- /types/interface.d.ts: -------------------------------------------------------------------------------- 1 | import { CID } from 'multiformats/cid'; 2 | import { BlockCodec } from 'multiformats/codecs/interface'; 3 | import { MultihashHasher } from 'multiformats/hashes/interface'; 4 | export interface HashMap { 5 | readonly cid: CID; 6 | get(key: string | Uint8Array): Promise; 7 | has(key: string | Uint8Array): Promise; 8 | size(): Promise; 9 | set(key: string | Uint8Array, value: V): Promise; 10 | delete(key: string | Uint8Array): Promise; 11 | values(): AsyncIterable; 12 | keys(): AsyncIterable; 13 | keysRaw(): AsyncIterable; 14 | entries(): AsyncIterable<[string, V]>; 15 | entriesRaw(): AsyncIterable<[Uint8Array, V]>; 16 | cids(): AsyncIterable; 17 | } 18 | export interface CreateOptions { 19 | blockCodec: BlockCodec; 20 | blockHasher: MultihashHasher; 21 | hasher?: MultihashHasher; 22 | hashBytes?: number; 23 | bitWidth?: number; 24 | bucketSize?: number; 25 | } 26 | export interface Loader { 27 | get(cid: CID): Promise; 28 | put(cid: CID, bytes: Uint8Array): Promise; 29 | } 30 | //# sourceMappingURL=interface.d.ts.map -------------------------------------------------------------------------------- /types/interface.d.ts.map: -------------------------------------------------------------------------------- 1 | {"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAE/D,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IAEjB,GAAG,CAAE,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,CAAC,GAAC,IAAI,CAAC,CAAA;IAE/C,GAAG,CAAE,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhD,IAAI,IAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAExB,GAAG,CAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvD,MAAM,CAAE,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhD,MAAM,IAAK,aAAa,CAAC,CAAC,CAAC,CAAA;IAE3B,IAAI,IAAK,aAAa,CAAC,MAAM,CAAC,CAAA;IAE9B,OAAO,IAAK,aAAa,CAAC,UAAU,CAAC,CAAA;IAErC,OAAO,IAAK,aAAa,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA;IAEtC,UAAU,IAAK,aAAa,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAA;IAE7C,IAAI,IAAK,aAAa,CAAC,GAAG,CAAC,CAAA;CAC5B;AAED,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC;IACpD,UAAU,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAEhC,WAAW,EAAE,eAAe,CAAA;IAE5B,MAAM,CAAC,EAAE,eAAe,CAAA;IAExB,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,GAAG,CAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IACnC,GAAG,CAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjD"} -------------------------------------------------------------------------------- /types/ipld-hashmap.d.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @ignore 3 | * @template V 4 | * @template {number} Codec 5 | * @param {Loader} loader 6 | * @param {CID|null} root 7 | * @param {CreateOptions} options 8 | * @returns {Promise>} 9 | */ 10 | export function _load(loader: Loader, root: CID | null, options: import("./interface").CreateOptions): Promise>; 11 | /** 12 | * Create a new {@link HashMap} instance, beginning empty, or loading from existing data in a 13 | * backing store. 14 | * 15 | * A backing store must be provided to make use of a HashMap, an interface to the store is given 16 | * through the mandatory `loader` parameter. The backing store stores IPLD blocks, referenced by 17 | * CIDs. `loader` must have two functions: `get(cid)` which should return the raw bytes (`Buffer` 18 | * or `Uint8Array`) of a block matching the given CID, and `put(cid, block)` that will store the 19 | * provided raw bytes of a block (`block`) and store it with the associated CID. 20 | * 21 | * @async 22 | * @template V 23 | * @template {number} Codec 24 | * @param {Loader} loader - A loader with `get(cid):block` and `put(cid, block)` functions for 25 | * loading an storing block data by CID. 26 | * @param {CreateOptions} options - Options for the HashMap. Defaults are provided but you can tweak 27 | * behavior according to your needs with these options. 28 | * @return {Promise>} - A HashMap instance, either loaded from an existing root block CID, or a new, 29 | * empty HashMap if no CID is provided. 30 | */ 31 | export function create(loader: Loader, options: import("./interface").CreateOptions): Promise>; 32 | /** 33 | * @template V 34 | * @template {number} Codec 35 | * @param {Loader} loader 36 | * @param {CID} root - A root of an existing HashMap. Provide a CID if you want to load existing 37 | * data. 38 | * @param {CreateOptions} options 39 | * @returns {Promise>} 40 | */ 41 | export function load(loader: Loader, root: CID, options: import("./interface").CreateOptions): Promise>; 42 | /** 43 | * 44 | */ 45 | export type IAMap = import('iamap').IAMap; 46 | /** 47 | * 48 | */ 49 | export type Store = import('iamap').Store; 50 | export type MultihashHasher = import('multiformats/hashes/interface').MultihashHasher; 51 | /** 52 | * 53 | */ 54 | export type HashMap = import('./interface').HashMap; 55 | /** 56 | * 57 | */ 58 | export type CreateOptions = import('./interface').CreateOptions; 59 | /** 60 | * 61 | */ 62 | export type Loader = import('./interface').Loader; 63 | import { CID } from 'multiformats/cid'; 64 | //# sourceMappingURL=ipld-hashmap.d.ts.map -------------------------------------------------------------------------------- /types/ipld-hashmap.d.ts.map: -------------------------------------------------------------------------------- 1 | {"version":3,"file":"ipld-hashmap.d.ts","sourceRoot":"","sources":["../ipld-hashmap.js"],"names":[],"mappings":"AAkVA;;;;;;;;GAQG;AACH,uDALW,MAAM,QACN,GAAG,GAAC,IAAI,qGAmJlB;AA9LC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wDAPW,MAAM,qGAShB;AAED;;;;;;;;GAQG;AACH,sDANW,MAAM,QACN,GAAG,qGAOb;;;;uBA1TU,OAAO,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;;;;uBAIxB,OAAO,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;8BAGxB,OAAO,+BAA+B,EAAE,eAAe;;;;yBAIvD,OAAO,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;;;;qDAKhC,OAAO,aAAa,EAAE,aAAa,CAAC,KAAK,EAAC,CAAC,CAAC;;;;qBAG5C,OAAO,aAAa,EAAE,MAAM;oBAvCrB,kBAAkB"} -------------------------------------------------------------------------------- /types/schema-validate.d.ts: -------------------------------------------------------------------------------- 1 | export function HashMapRoot(obj: any): boolean; 2 | export function HashMapNode(obj: any): boolean; 3 | export function Element(obj: any): boolean; 4 | export function Bucket(obj: any): boolean; 5 | export function BucketEntry(obj: any): boolean; 6 | //# sourceMappingURL=schema-validate.d.ts.map -------------------------------------------------------------------------------- /types/schema-validate.d.ts.map: -------------------------------------------------------------------------------- 1 | {"version":3,"file":"schema-validate.d.ts","sourceRoot":"","sources":["../schema-validate.js"],"names":[],"mappings":"AAwC4B,iCAAK,GAAG,GAAG,OAAO,CAAA;AAAlB,iCAAK,GAAG,GAAG,OAAO,CAAA;AAAlB,6BAAK,GAAG,GAAG,OAAO,CAAA;AAAlB,4BAAK,GAAG,GAAG,OAAO,CAAA;AAAlB,iCAAK,GAAG,GAAG,OAAO,CAAA"} --------------------------------------------------------------------------------