|
5 | 5 |
|
6 | 6 | > A set of utilities to help identify IPFS resources on the web
|
7 | 7 |
|
8 |
| -## Table of contents <!-- omit in toc --> |
9 |
| - |
10 |
| -- [Install](#install) |
11 |
| - - [Browser `<script>` tag](#browser-script-tag) |
12 |
| -- [Usage](#usage) |
13 |
| -- [API](#api) |
14 |
| - - [Content Identifiers](#content-identifiers) |
15 |
| - - [`isIPFS.multihash(hash)`](#isipfsmultihashhash) |
16 |
| - - [`isIPFS.cid(hash)`](#isipfscidhash) |
17 |
| - - [`isIPFS.base32cid(hash)`](#isipfsbase32cidhash) |
18 |
| - - [URLs](#urls) |
19 |
| - - [`isIPFS.url(url)`](#isipfsurlurl) |
20 |
| - - [`isIPFS.ipfsUrl(url)`](#isipfsipfsurlurl) |
21 |
| - - [`isIPFS.ipnsUrl(url)`](#isipfsipnsurlurl) |
22 |
| - - [Paths](#paths) |
23 |
| - - [`isIPFS.path(path)`](#isipfspathpath) |
24 |
| - - [`isIPFS.urlOrPath(path)`](#isipfsurlorpathpath) |
25 |
| - - [`isIPFS.ipfsPath(path)`](#isipfsipfspathpath) |
26 |
| - - [`isIPFS.ipnsPath(path)`](#isipfsipnspathpath) |
27 |
| - - [`isIPFS.cidPath(path)`](#isipfscidpathpath) |
28 |
| - - [Subdomains](#subdomains) |
29 |
| - - [`isIPFS.subdomain(url)`](#isipfssubdomainurl) |
30 |
| - - [`isIPFS.ipfsSubdomain(url)`](#isipfsipfssubdomainurl) |
31 |
| - - [`isIPFS.ipnsSubdomain(url)`](#isipfsipnssubdomainurl) |
32 |
| - - [Multiaddrs](#multiaddrs) |
33 |
| - - [`isIPFS.multiaddr(addr)`](#isipfsmultiaddraddr) |
34 |
| - - [`isIPFS.peerMultiaddr(addr)`](#isipfspeermultiaddraddr) |
35 |
| -- [API Docs](#api-docs) |
36 |
| -- [License](#license) |
37 |
| -- [Contribution](#contribution) |
38 |
| - |
39 |
| -## Install |
| 8 | +# About |
40 | 9 |
|
41 |
| -```console |
42 |
| -$ npm i is-ipfs |
43 |
| -``` |
44 |
| - |
45 |
| -### Browser `<script>` tag |
| 10 | +A suite of util methods that provides efficient validation. |
46 | 11 |
|
47 |
| -Loading this module through a script tag will make it's exports available as `IsIpfs` in the global namespace. |
| 12 | +Detection of IPFS Paths and identifiers in URLs is a two-stage process: |
48 | 13 |
|
49 |
| -```html |
50 |
| -<script src="https://unpkg.com/is-ipfs/dist/index.min.js"></script> |
51 |
| -``` |
| 14 | +1. `pathPattern`/`pathGatewayPattern`/`subdomainGatewayPattern` regex is applied to quickly identify potential candidates |
| 15 | +2. proper CID validation is applied to remove false-positives |
52 | 16 |
|
53 |
| -## Usage |
| 17 | +## Example |
54 | 18 |
|
55 |
| -```javascript |
| 19 | +```TypeScript |
56 | 20 | import * as isIPFS from 'is-ipfs'
|
57 | 21 |
|
58 | 22 | isIPFS.multihash('QmYjtig7VJQ6XsnUjqqJvj7QaMcCAwtrgNdahSiFofrE7o') // true
|
@@ -134,117 +98,31 @@ isIPFS.peerMultiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQ
|
134 | 98 | isIPFS.peerMultiaddr('/ip4/127.0.0.1/udp/1234') // false (key missing)
|
135 | 99 | ```
|
136 | 100 |
|
137 |
| -## API |
138 |
| - |
139 |
| -A suite of util methods that provides efficient validation. |
140 |
| - |
141 |
| -Detection of IPFS Paths and identifiers in URLs is a two-stage process: |
142 |
| - |
143 |
| -1. `pathPattern`/`pathGatewayPattern`/`subdomainGatewayPattern` regex is applied to quickly identify potential candidates |
144 |
| -2. proper CID validation is applied to remove false-positives |
145 |
| - |
146 |
| -### Content Identifiers |
147 |
| - |
148 |
| -#### `isIPFS.multihash(hash)` |
149 |
| - |
150 |
| -Returns `true` if the provided string or `Uint8Array` is a valid `multihash` or `false` otherwise. |
151 |
| - |
152 |
| -#### `isIPFS.cid(hash)` |
153 |
| - |
154 |
| -Returns `true` if the provided string, `Uint8Array` or [`CID`](https://github.com/multiformats/js-multiformats/#readme) object represents a valid [CID](https://docs.ipfs.io/guides/concepts/cid/) or `false` otherwise. |
155 |
| - |
156 |
| -#### `isIPFS.base32cid(hash)` |
157 |
| - |
158 |
| -Returns `true` if the provided string is a valid `CID` in Base32 encoding or `false` otherwise. |
159 |
| - |
160 |
| -### URLs |
161 |
| - |
162 |
| -#### `isIPFS.url(url)` |
163 |
| - |
164 |
| -Returns `true` if the provided string is a valid IPFS or IPNS url or `false` otherwise. |
165 |
| - |
166 |
| -#### `isIPFS.ipfsUrl(url)` |
167 |
| - |
168 |
| -Returns `true` if the provided string is a valid IPFS url or `false` otherwise. |
169 |
| - |
170 |
| -#### `isIPFS.ipnsUrl(url)` |
171 |
| - |
172 |
| -Returns `true` if the provided string is a valid IPNS url or `false` otherwise. |
| 101 | +# Install |
173 | 102 |
|
174 |
| -### Paths |
175 |
| - |
176 |
| -Standalone validation of IPFS Paths: `/ip(f|n)s/<cid>/..` |
177 |
| - |
178 |
| -#### `isIPFS.path(path)` |
179 |
| - |
180 |
| -Returns `true` if the provided string is a valid IPFS or IPNS path or `false` otherwise. |
181 |
| - |
182 |
| -#### `isIPFS.urlOrPath(path)` |
183 |
| - |
184 |
| -Returns `true` if the provided string is a valid IPFS or IPNS url or path or `false` otherwise. |
185 |
| - |
186 |
| -#### `isIPFS.ipfsPath(path)` |
187 |
| - |
188 |
| -Returns `true` if the provided string is a valid IPFS path or `false` otherwise. |
189 |
| - |
190 |
| -#### `isIPFS.ipnsPath(path)` |
191 |
| - |
192 |
| -Returns `true` if the provided string is a valid IPNS path or `false` otherwise. |
193 |
| - |
194 |
| -#### `isIPFS.cidPath(path)` |
195 |
| - |
196 |
| -Returns `true` if the provided string is a valid "CID path" (IPFS path without `/ipfs/` prefix) or `false` otherwise. |
197 |
| - |
198 |
| -### Subdomains |
199 |
| - |
200 |
| -Validated subdomain convention: `cidv1b32.ip(f|n)s.domain.tld` |
201 |
| - |
202 |
| -#### `isIPFS.subdomain(url)` |
203 |
| - |
204 |
| -Returns `true` if the provided `url` string includes a valid IPFS, looks like IPNS/DNSLink subdomain or `false` otherwise. |
205 |
| - |
206 |
| -#### `isIPFS.ipfsSubdomain(url)` |
207 |
| - |
208 |
| -Returns `true` if the provided `url` string includes a valid IPFS subdomain (case-insensitive CIDv1) or `false` otherwise. |
209 |
| - |
210 |
| -#### `isIPFS.ipnsSubdomain(url)` |
211 |
| - |
212 |
| -Returns `true` if the provided `url` string looks like a valid IPNS subdomain |
213 |
| -(CIDv1 with `libp2p-key` multicodec or something that looks like a FQDN, for example `en.wikipedia-on-ipfs.org.ipns.localhost:8080`) or `false` |
214 |
| -otherwise. |
215 |
| - |
216 |
| -**Note:** `ipnsSubdomain` method works in offline mode: it does not perform |
217 |
| -actual IPNS record lookup over DHT or other content routing method. It may |
218 |
| -return false-positives: |
219 |
| - |
220 |
| -- To ensure IPNS record exists, make a call to `/api/v0/name/resolve?arg=<ipnsid>` |
221 |
| -- To ensure DNSLink exists, make a call to `/api/v0/dns?arg=<fqdn>` |
222 |
| - |
223 |
| -### Multiaddrs |
224 |
| - |
225 |
| -Below methods provide basic detection of [multiaddr](https://github.com/multiformats/multiaddr)s: composable and future-proof network addresses. |
226 |
| - |
227 |
| -Complex validation of multiaddr can be built using `isIPFS.multiaddr` and [`mafmt`](https://github.com/multiformats/js-mafmt) library. |
228 |
| - |
229 |
| -#### `isIPFS.multiaddr(addr)` |
| 103 | +```console |
| 104 | +$ npm i is-ipfs |
| 105 | +``` |
230 | 106 |
|
231 |
| -Returns `true` if the provided `string`, [`Multiaddr`](https://github.com/multiformats/js-multiaddr) or `Uint8Array` represents a valid multiaddr or `false` otherwise. |
| 107 | +## Browser `<script>` tag |
232 | 108 |
|
233 |
| -#### `isIPFS.peerMultiaddr(addr)` |
| 109 | +Loading this module through a script tag will make it's exports available as `IsIpfs` in the global namespace. |
234 | 110 |
|
235 |
| -Returns `true` if the provided `string`, [`Multiaddr`](https://github.com/multiformats/js-multiaddr) or `Uint8Array` represents a valid libp2p peer multiaddr (matching [`P2P` format from `mafmt`](https://github.com/multiformats/js-mafmt#api)) or `false` otherwise. |
| 111 | +```html |
| 112 | +<script src="https://unpkg.com/is-ipfs/dist/index.min.js"></script> |
| 113 | +``` |
236 | 114 |
|
237 |
| -## API Docs |
| 115 | +# API Docs |
238 | 116 |
|
239 | 117 | - <https://ipfs-shipyard.github.io/is-ipfs>
|
240 | 118 |
|
241 |
| -## License |
| 119 | +# License |
242 | 120 |
|
243 | 121 | Licensed under either of
|
244 | 122 |
|
245 | 123 | - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
|
246 | 124 | - MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
|
247 | 125 |
|
248 |
| -## Contribution |
| 126 | +# Contribution |
249 | 127 |
|
250 | 128 | Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
|
0 commit comments