Add code examples to repository

[RichardLitt]

Let's also add them on IPFS, and point to the repo and IPFS versions directly.

[kvutien]

I fully agree, @RichardLitt . We never give enough examples, in a tutorial.

I made a sample JavaScript of 01_Basics for my own usage. You'll recognize most of the REPL commands. It's immediately usable by any beginner looking for sample code to include in their apps.

I copy it below because I don't know where the maintainers of the Tutorial want to structure the repository itself. Personally I'd add it as a bonus at the end of 01_Basics.md to make it easier for a beginner to find it. A repo is always a bit daunting to explore.

So here is the JavaScript code, for whatever if can help:

/* 
 * Main JavaScript program to exercise the functions of the Tutorial '01_Basics.md'
 * June 2021
 * [email protected] and [email protected]
 */
// Require the dependencies
const Ipfs = require ('ipfs');
const OrbitDB = require ('orbit-db');

// make a global variable of the IPFS node interface
var node;

// main function: create IPFS node and OrbitDB node + database
async function create() {
    console.log('  -> calling create IPFS node;')
    // create an IPFS node
    node = await Ipfs.create({
        preload: {enabled: false},
        repo: './ipfs',
        EXPERIMENTAL: {pubsub: true},
        config: {
            Bootstrap: [],
            Addresses: {Swarm: []}
        }
    })
    console.log('  -> calling init database;')
    // follow with orbitDB database demo
    _init()
}

async function _init() {
    // create an OrbitDB interface instance on the IPFS node
    const orbitdb = await OrbitDB.createInstance(node)
    console.log("  --> IPFS node's id: ", orbitdb.identity.id)
    const defaultOptions = { accessController: {
        write: [orbitdb.identity.id] }
    }
    const docStoreOptions = {
        ...defaultOptions,
        indexBy: 'hash'
    }
    // create a specific "docstore' database
    const pieces = await orbitdb.docstore('pieces', docStoreOptions)
    console.log("  ----> pieces.options.accessControllerAddress = ", pieces.options.accessControllerAddress)
    console.log("  ----> pieces.id = ", pieces.id)
    console.log("  ----> pieces.identity._id = ", pieces.identity._id)
    console.log("  ----> pieces.address root = ", pieces.address.root, ', path =', pieces.address.path)
    // ... more to come
}

create();

Executing it will give

% node index.js                 
  -> calling create IPFS node;
  -> calling init database;
  --> IPFS node's id:  03ecc23e7dfa8d1837ba979e719e934879c80dbd62fa0f42c84093f3ae53090e86
  ----> pieces.options.accessControllerAddress =  /ipfs/zdpuAxrg7DS7h7bdeuBuV5JFxjgc4bhVEajGxJUsLH2kjvCqv
  ----> pieces.id =  /orbitdb/zdpuAxtiGj9xZaXCJx1z5852ZUYWJ8TjHeKBpMruUs7nNS8CC/pieces
  ----> pieces.identity._id =  03ecc23e7dfa8d1837ba979e719e934879c80dbd62fa0f42c84093f3ae53090e86
  ----> pieces.address root =  zdpuAxtiGj9xZaXCJx1z5852ZUYWJ8TjHeKBpMruUs7nNS8CC , path = pieces

end execution by typing Control-C

[kvutien]

Allow a humble feedback from a self-learning beginner.

There are 2 kinds of tutorials: (1) interactive courses and (2) offline self-paced courses

1. when you do interactive courses, using a REPL is nice because the audience can repeat the commands and see the results.
2. for offline self-paced courses, REPL is a pain because usually the learner is always diverting from the thread to do stack Exchange research for his/her questions and then come back. Then the whole REPL sequence has to be repeated

In addition, all self-learners follow the course for a specific programming purpose, so at the end they have to convert the REPL into a JavaScript program. Curently it's an exercise left to the reader. It would improve tremensously the value of the course if such JavaScript programs were provided. This is what I did for my own needs with the code above.

It would help if each tutorial ends with a sample code that reproduces the REPL made during the tutorial.

Note: ProtoSchool is between the 2. It is self-paced, without REPL but its coding exercises have immediate feed back and solutions, like an interactive REPL-based course. It's marvelous and as good as it can be, replicating the feeling of REPL using code snippets. But the feedback messages don't give much clue on what went wrong when there is a mistake. With a piece of code, the learner can add liberally console.log to find what went wrong.

My 2 cents...

[aphelionz]

Thank you for the thoughtful feedback!

[kvutien]

Questions:

1. Am I right if I remove from the IPFS options EXPERIMENTAL: {pubsub: true}, ? With the recent IPFS pubsub true is no more experimental?
2. Am I right if I replace in this code require('ipfs') by ('ipfs-core') which is lighter? in a JavaScript program I don't need the REPL

You may reply "just try" 😂 but I wanted to make sure of the answer from an IPFS/OrbitDB insider

[aphelionz]

1. Yes, I believe you can remove the EXPERIMENTAL flag
2. I don't know, tbh! "just try" :)

[kvutien]

Both worked. Thanks.

So we can answer positively to both. But of course we haven't really tried exercising pubsub from OrbitDB in this short program. At least it doesn't hang.

kvutien@VTKT5 orbitdb-ch1 % node index.js
  -> calling create IPFS node;
  -> calling init database;
  --> IPFS node's id:  03ecc23e7dfa8d1837ba979e719e934879c80dbd62fa0f42c84093f3ae53090e86
  ----> pieces.options.accessControllerAddress =  /ipfs/zdpuAxrg7DS7h7bdeuBuV5JFxjgc4bhVEajGxJUsLH2kjvCqv
  ----> pieces.id =  /orbitdb/zdpuAxtiGj9xZaXCJx1z5852ZUYWJ8TjHeKBpMruUs7nNS8CC/pieces
  ----> pieces.identity._id =  03ecc23e7dfa8d1837ba979e719e934879c80dbd62fa0f42c84093f3ae53090e86
  ----> pieces.address root =  zdpuAxtiGj9xZaXCJx1z5852ZUYWJ8TjHeKBpMruUs7nNS8CC , path = pieces