docs: bring examples back

Author: achingbrain

.travis.yml

@@ -62,7 +62,7 @@ jobs:
   include:
     - stage: check
       script:
-        - npm run build -- $RUN_SINCE --scope={ipfs,ipfs-http-client} -- -- --bundlesize
+        - npm run build -- $RUN_SINCE --scope={ipfs,ipfs-http-client}
         - npm run dep-check -- $RUN_SINCE -- -- -- -i electron-webrtc
         - npm run lint -- $RUN_SINCE --concurrency 1
 
@@ -128,6 +128,14 @@ jobs:
       script:
         - npm run test:interop:electron-renderer -- $RUN_SINCE -- -- --bail --timeout 10000
 
+    - stage: test
+      name: examples
+      script:
+        - npx json -I -f ./lerna.json -e "this.packages.push('examples/*')"
+        - npm run reset
+        - npm install
+        - npm run test -- --scope=example* --concurrency=1
+
     - stage: release-rc-npm
       # only run on changes to master
       if: branch = master AND type = push AND fork = false
@@ -208,12 +216,5 @@ jobs:
       script:
         - npm run test:external -- -- -- https://github.com/decentralized-identity/sidetree.git --deps=ipfs@next
 
-    - stage: test-external
-      # only run on changes to master
-      if: branch = master AND type = push AND fork = false
-      name: external - examples
-      script:
-        - npm run test:external -- -- -- https://github.com/ipfs-shipyard/js-ipfs-examples.git --deps=ipfs@next  --deps=ipfs-http-client@next
-
 notifications:
   email: false

README.md

@@ -26,7 +26,7 @@ We've come a long way, but this project is still in Alpha, lots of development i
 
 ## Getting started
 
-* Look into the [examples repo](https://github.com/ipfs-shipyard/js-ipfs-examples) to learn how to spawn an IPFS node in Node.js and in the Browser
+* Look into the [examples](/examples) to learn how to spawn an IPFS node in Node.js and in the Browser
 * Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node
 * Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
 * Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
@@ -47,7 +47,7 @@ We've come a long way, but this project is still in Alpha, lots of development i
 ## Documentation
 
 * [Core API](./docs/core-api)
-* [Examples](https://github.com/ipfs-shipyard/js-ipfs-examples)
+* [Examples](./examples)
 * [Development](./docs/DEVELOPMENT.md)
 
 ## Structure

docs/BROWSERS.md

@@ -71,4 +71,4 @@ document.addEventListener('DOMContentLoaded', async () => {
 </script>
 ```
 
-More advanced examples and tutorials can be found in the [examples repo](https://github.com/ipfs-shipyard/js-ipfs-examples)
+More advanced examples and tutorials can be found in the [examples](../examples)

examples/browser-add-readable-stream/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [2.0.1](https://github.com/ipfs/js-ipfs/compare/example-browser-add-readable-stream@[email protected]) (2020-04-08)
+
+**Note:** Version bump only for package example-browser-add-readable-stream
+
+
+
+
+
+# 2.0.0 (2020-03-31)
+
+
+### Bug Fixes
+
+* examples after files API refactor ([#1740](https://github.com/ipfs/js-ipfs/issues/1740)) ([34ec036](https://github.com/ipfs/js-ipfs/commit/34ec036b0df9563a014c1348f0a056c1f98aadad))
+
+
+### Code Refactoring
+
+* export types and utilities statically ([#1908](https://github.com/ipfs/js-ipfs/issues/1908)) ([79d7fef](https://github.com/ipfs/js-ipfs/commit/79d7fef7d28c0e0405fb69af149ff09681ac4273))
+
+
+### BREAKING CHANGES
+
+* `ipfs.util.isIPFS` and `ipfs.util.crypto` have moved to static exports and should be accessed via `const { isIPFS, crypto } = require('ipfs')`.
+
+The modules available under `ipfs.types.*` have also become static exports.
+
+License: MIT
+Signed-off-by: Alan Shaw <[email protected]>

examples/browser-add-readable-stream/README.md

@@ -0,0 +1,20 @@
+# Using duplex streams to add files to IPFS in the browser
+
+If you have a number of files that you'd like to add to IPFS and end up with a hash representing the directory containing your files, you can invoke [`ipfs.add`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#add) with an array of objects.
+
+But what if you don't know how many there will be in advance?  You can add multiple files to a directory in IPFS over time by using [`ipfs.addReadableStream`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#addreadablestream).
+
+## Before you start
+
+First clone this repo, install dependencies in the project root and build the project.
+
+```console
+$ git clone https://github.com/ipfs/js-ipfs.git
+$ cd js-ipfs
+$ npm install
+$ npm run build
+```
+
+## Running the example
+
+See [`index.js`](./index.js) for a working example and open [`index.html`](./index.html) in your browser to see it run.

examples/browser-add-readable-stream/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Add readable stream</title>
+  </head>
+  <body>
+    <pre id="output"></pre>
+    <script src="../../node_modules/ipfs/dist/index.min.js"></script>
+    <script src="index.js"></script>
+  </body>
+</html>

examples/browser-add-readable-stream/index.js

@@ -0,0 +1,69 @@
+'use strict'
+
+/* global Ipfs */
+/* eslint-env browser */
+
+const main = async () => {
+  const repoPath = `ipfs-${Math.random()}`
+  const ipfs = await Ipfs.create({ repo: repoPath })
+
+  const directoryName = 'directory'
+
+  // Our list of files
+  const inputFiles = createFiles(directoryName)
+
+  const directoryHash = await streamFiles(ipfs, directoryName, inputFiles)
+
+  const fileList = await ipfs.ls(directoryHash)
+
+  log(`\n--\n\nDirectory contents:\n\n${directoryName}/ ${directoryHash}`)
+
+  fileList.forEach((file, index) => {
+    log(` ${index < fileList.length - 1 ? '\u251C' : '\u2514'}\u2500 ${file.name} ${file.path} ${file.hash}`)
+  })
+}
+
+const createFiles = (directory) => {
+  return [{
+    path: `${directory}/file1.txt`,
+
+    // content could be a stream, a url, a Buffer, a File etc
+    content: 'one'
+  }, {
+    path: `${directory}/file2.txt`,
+    content: 'two'
+  }, {
+    path: `${directory}/file3.txt`,
+    content: 'three'
+  }]
+}
+
+const streamFiles = async (ipfs, directory, files) => {
+  // Create a stream to write files to
+  const stream = new ReadableStream({
+    start(controller) {
+      for (let i = 0; i < files.length; i++) {
+        // Add the files one by one
+        controller.enqueue(files[i])
+      }
+
+      // When we have no more files to add, close the stream
+      controller.close()
+    }
+  })
+
+  for await (const data of ipfs.add(stream)) {
+    log(`Added ${data.path} hash: ${data.hash}`)
+
+    // The last data event will contain the directory hash
+    if (data.path === directory) {
+      return data.cid
+    }
+  }
+}
+
+const log = (line) => {
+  document.getElementById('output').appendChild(document.createTextNode(`${line}\r\n`))
+}
+
+main()

examples/browser-add-readable-stream/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "example-browser-add-readable-stream",
+  "description": "How to add readable streams in the browser",
+  "version": "2.0.1",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "serve": "http-server public -a 127.0.0.1 -p 8888",
+    "start": "npm run serve",
+    "test": "test-ipfs-example"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "devDependencies": {
+    "ipfs": "^0.46.0",
+    "test-ipfs-example": "^2.0.3"
+  }
+}

examples/browser-add-readable-stream/test.js

@@ -0,0 +1,13 @@
+'use strict'
+
+module.exports = {
+  'Add readable stream example': function (browser) {
+    browser
+      .url(process.env.IPFS_EXAMPLE_TEST_URL)
+      .waitForElementVisible('#output')
+
+    browser.expect.element('#output').text.to.contain('directory/ QmVgJePRxp1vhRxDcJWdmuFGfUB5S5RYTtG1NR3bQM4BBn')
+
+    browser.end()
+  }
+}

examples/browser-browserify/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [1.1.1](https://github.com/ipfs/js-ipfs/compare/[email protected]@1.1.1) (2020-04-08)
+
+**Note:** Version bump only for package example-browser-browserify
+
+
+
+
+
+# 1.1.0 (2020-03-31)
+
+
+### Bug Fixes
+
+* examples after files API refactor ([#1740](https://github.com/ipfs/js-ipfs/issues/1740)) ([34ec036](https://github.com/ipfs/js-ipfs/commit/34ec036b0df9563a014c1348f0a056c1f98aadad))
+
+
+### Features
+
+* implementing the new streaming interfaces ([#1086](https://github.com/ipfs/js-ipfs/issues/1086)) ([2c4b8b3](https://github.com/ipfs/js-ipfs/commit/2c4b8b325b94d4506b87441f06c5d29bb6f37f72))

examples/browser-browserify/README.md

@@ -0,0 +1,29 @@
+# Bundle js-ipfs with Browserify!
+
+In this example, you will find a boilerplate you can use to guide yourself into bundling js-ipfs with [browserify](http://browserify.org/), so that you can use it in your own web app!
+
+## Before you start
+
+First clone this repo, install dependencies in the project root and build the project.
+
+```console
+$ git clone https://github.com/ipfs/js-ipfs.git
+$ cd js-ipfs
+$ npm install
+$ npm run build
+```
+
+## Running the example
+
+In this directory run:
+
+```bash
+> npm start
+```
+
+Now open your browser at `http://localhost:8888`
+
+You should see the following:
+
+![](https://ipfs.io/ipfs/QmNtpcWCEd6LjdPNfBFDaVZdD4jpgT8ZTAwoFJXKhYMJdo/1.png)
+![](https://ipfs.io/ipfs/QmNtpcWCEd6LjdPNfBFDaVZdD4jpgT8ZTAwoFJXKhYMJdo/2.png)

examples/browser-browserify/img/1.png

@@ -0,0 +1,27 @@
+{
+  "name": "example-browser-browserify",
+  "description": "Bundle js-ipfs with Browserify",
+  "version": "1.1.1",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "bundle": "browserify src/index.js > public/bundle.js",
+    "serve": "http-server public -a 127.0.0.1 -p 8888",
+    "start": "npm run bundle && npm run serve",
+    "clean": "rm -rf public/bundle.js",
+    "test": "test-ipfs-example"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "devDependencies": {
+    "browserify": "^16.2.3",
+    "concat-stream": "^2.0.0",
+    "execa": "^4.0.0",
+    "http-server": "^0.11.1",
+    "ipfs": "^0.46.0",
+    "test-ipfs-example": "^2.0.3"
+  },
+  "browser": {
+    "ipfs": "ipfs/dist/index.min.js"
+  }
+}

examples/browser-browserify/img/2.png

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8"/>
+    <title>js-ipfs example</title>
+    <script src="bundle.js"></script>
+    <style>
+      .content {
+        border: 1px solid black;
+        padding: 10px;
+        margin: 5px 0;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>JS IPFS - Add data to IPFS from the browser</h1>
+    <textarea id="source" placeholder="Enter some text here"></textarea>
+    <button id="store">Add text to ipfs</button>
+    <div id="output" style="display: none">
+      <div>found in ipfs:</div>
+      <div class="content" id="cid">[ipfs cid]</div>
+      <div class="content" id="content">[ipfs content]</div>
+    </div>
+  </body>
+</html>

examples/browser-browserify/package.json

@@ -0,0 +1,31 @@
+'use strict'
+
+const IPFS = require('ipfs')
+
+document.addEventListener('DOMContentLoaded', async () => {
+  const node = await IPFS.create({ repo: String(Math.random() + Date.now()) })
+
+  console.log('IPFS node is ready')
+
+  async function store () {
+    const toStore = document.getElementById('source').value
+
+    for await (const file of node.add(toStore)) {
+      if (file && file.cid) {
+        console.log('successfully stored', file.cid)
+
+        await display(file.cid)
+      }
+    }
+  }
+
+  async function display (cid) {
+    for await (const data of node.cat(cid)) {
+      document.getElementById('cid').innerText = cid
+      document.getElementById('content').innerText = data
+      document.getElementById('output').setAttribute('style', 'display: block')
+    }
+  }
+
+  document.getElementById('store').onclick = store
+})

examples/browser-browserify/public/index.html

@@ -0,0 +1,21 @@
+'use strict'
+
+const pkg = require('./package.json')
+
+module.exports = {
+  [pkg.name]: function (browser) {
+    browser
+      .url(process.env.IPFS_EXAMPLE_TEST_URL)
+      .waitForElementVisible('#source')
+      .setValue('#source', 'hello')
+      .waitForElementVisible('#store')
+      .pause(1000)
+      .click('#store')
+      .waitForElementVisible('#output')
+
+    browser.expect.element('#cid').text.to.contain('QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX')
+    browser.expect.element('#content').text.to.contain('hello')
+
+    browser.end()
+  }
+}

examples/browser-browserify/src/index.js

@@ -0,0 +1,3 @@
+# required because react-scripts scans *up* the tree from this project and finds
+# a conflicting version of eslint in the node_modules dir for js-ipfs.
+SKIP_PREFLIGHT_CHECK=true