Dev

blog/2019-05-29-hello-world.md

@@ -1,10 +1,9 @@
 ---
-id: hello-world
+slug: hello-world
 title: Hello
 author: arso-project
 author_title: coop
 author_url: https://github.com/arso-project
-author_image_url: 
 tags: [hello, sonar]
 ---
 

build-with-apidocs.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+set -v
+
+if [ ! -d tmp ]; then
+  mkdir tmp -p
+  pushd tmp
+  git clone https://github.com/arso-project/sonar.git
+  pushd sonar
+else
+  pushd tmp
+  pushd sonar
+  git pull
+fi
+yarn
+yarn docs:client
+popd
+popd
+mv tmp/sonar/packages/client/docs static/apidocs-client
+yarn build
+rm -r tmp

docs/api-client.md → docs/api/api-client.md

@@ -6,6 +6,8 @@ title: Client
 
 The primary way to interact with Sonar is through the *Sonar Client*. The Client talks to the Sonar daemon over HTTP. The Sonar daemon is part of the P2P network, exchanges data with other peers and indexes the data in your islands.
 
+**<a href="/apidocs-client" target="_blank">API docs for the client</a>**
+
 ## Get started
 
 The client works both in browsers and in NodeJS. When using in browser, you currently need to have a bundling setup that supports CommonJS (e.g. webpack or browserify).

docs/guides/collections.md

@@ -0,0 +1,54 @@
+---
+title: Collections
+id: collections
+---
+
+## What is a Collection
+An collection is a set of feeds that are shared among peers.
+A feed is an append-only log of records. Each feed is only writable from a single device.
+A record is a unit of data. Each record has a type, a ref and a value.
+
+Collections are always part of a Workspace.
+
+
+## Add or open collection
+
+To add a new collection to the workspace we simply call the ``createCollection()``` function to open it we use ``openCollection()``` as for example in this code snippet:
+
+
+```js
+/**
+ * Check if the collection already exists if not create a new collection
+ * @returns opened || new collection
+ */
+export async function Collection(): Promise<Collection> {
+  if (!collection) {
+    try {
+      collection = await workspace.openCollection(collectionName)
+    } catch (err: any) {
+      collection = await workspace.createCollection(collectionName)
+    }
+    //  console.log('opened collection', collection.key.toString('hex'))
+    await ensureSchema(collection, schema)
+  }
+  return collection
+}
+```
+
+## Collection prooperties
+
+Various getters are available to retrieve the parameters of the collection:
+
+* `collection.key` is the hex-encoded *primary key* of the collection. Sharing this key gives *read access* to the collection.
+
+* `collection.info` contains a list of the feeds and other status information.
+
+* `collection.length` is the number of records in this collection.
+
+## Database
+
+Each collection forms a database of `Record`s. A record is a mutable, versioned record of data. Each record has a type, a unique ID and a JSON value. Through its type, a record is associated with a type schema.
+
+Records are created through `collection.put()` and read through `collection.get()` and `collection.query()`.
+
+See the <a href="/apidocs-client/classes/Collection.html" target="_blank">API docs</a> for the supported parameters and additional methods.

docs/guides/files.md

@@ -0,0 +1,31 @@
+---
+title: Files
+id: files
+---
+
+Each Sonar collection has a file store with a simple-to-use API to read and write file assets.
+
+To use the files API, open a Sonar collection as usual.
+```js
+import { Workspace } from '@arsonar/client'
+const workspace = new Workspace()
+const collection = await workspace.openCollection('default')
+```
+
+The file API has methods to read and write files.
+
+```js
+const content = 'foo' // can also be a Uint8Array or a ReadableStream
+const file = await collection.files.createFile(content)
+// file is a Sonar record of type 'sonar/file'
+console.log(file.id) // this logs the File ID
+const loadedContent = await collection.files.readFile(file.id, { responseType: 'text' })
+console.log(loadedContent) // logs "foo"
+await collection.files.updateFile(file.id, "bar")
+// now the file content is updated.
+const url = collection.files.getURL(file.id)
+// url now is a HTTP url to the file content.
+```
+
+See the <a href="/apidocs-client/classes/Files.html" target="_blank">API docs</a> for the supported parameters and additional methods.
+

docs/guides/runServer.md

@@ -0,0 +1,67 @@
+---
+title: Run a Server
+id: runServer
+---
+
+The usual setup is that you run sonar-server on localhost and then interact with Sonar through the client, the UI running on http://localhost:9191 or the CLI. The CLI can be invoked with ./sonar from the root of this repository, and is also used to start the server.
+
+## Installation
+
+```bash
+npm install -g @arsonar/server
+sonar help
+sonar start
+```
+
+## Development
+
+> Note: At the moment [yarn 1](https://classic.yarnpkg.com/) is recommended, please [install it according to the instructions](https://classic.yarnpkg.com/en/docs/install#debian-stable).
+
+```bash
+# clone the sonar repository
+git clone https://github.com/arso-project/sonar.git
+cd sonar
+# install dependencies of all workspaces
+yarn
+# (re)build the user interface and docs
+yarn run rebuild
+# when developing on something that uses the ESM version of the
+# `@arsonar/client` library: watch and rebuild on changes.
+yarn dev:client
+```
+
+You can start sonar with `./sonar` from the repository root.
+
+If the start fails with errors related to `sonar-tantivy`, try to redownload or rebuild sonar-tantivy (the search engine included in sonar):
+
+```
+yarn run build:sonar-tantivy
+```
+
+If the start fails with errors related to `client`, try to rebuild client :
+
+```
+yarn run build:client
+```
+
+```bash
+# start the sonar server
+./sonar start
+
+# start the sonar server in dev mode
+./sonar start --dev
+
+```
+
+## Running the examples
+
+This repo includes a few examples. To run them locally, do the following:
+
+```bash
+# build the client library
+yarn build:client
+# start sonar
+./sonar start --disable-authentication --dev
+# run the example from the examples/ folder
+yarn example react
+```

docs/guides/search.md

@@ -0,0 +1,20 @@
+---
+title: Search
+id: search
+---
+
+To search the records of a collection we can issue a query which returns an array with the matching records.
+
+```js
+(async) query(name, args, optsopt) → {Promise.<Array.<Record>>}
+```
+
+The arguments for the query. Depends on the query being used. For records: `{ schema, name, id }` For history: `{ from: timestamp, to: timestamp }` For search: Either a "string" for a simple full-text search, or a tantivy query object. For indexes: `{ schema, prop, value, from, to, reverse, limit }` (to be documented) For relations: `{ subject, object, predicate }` where subject and object are ids and predicate is type #field
+
+Here is a small example from our peerBooks App which will return the records for the schema Book:
+
+```js
+  const records = await collection.query('records', {
+    type: 'sonar-peerBooks/Book'
+  })
+```

docs/guides/workspace.md

@@ -0,0 +1,30 @@
+---
+title: Workspace
+id: workspace
+---
+If you start Sonar it comes with a Default Workspace 
+
+When you start Sonar it provides a default workspace. Workspaces are our endpoints in which collections can be managed, more about this under the point Collections.
+
+There can be multiple workspaces on one Sonar server.
+
+To create a new workspace you have to pass token and URL of the server for example like this in JavaScript:
+
+```js
+import { Workspace } from '@arsonar/client'
+/**
+ * Get the URL and access token for 
+ * the Sonar instance running in the background. 
+ */
+const url = process.env.SONAR_URL || 'http://localhost:9191/api/v1/default'
+const token = process.env.SONAR_TOKEN
+/**
+ * Initializing a client 
+ */
+export const workspace = new Workspace({
+  url,
+  accessCode: token
+});
+```
+
+Now you can create, update, open and display collections on the workspace. Furthermore the workspace offers the possibility to manage the login of the client. More about the workspace can be found in the API description: [Workspace](https://sonar-apidocs.dev.arso.xyz/Workspace.html)

docs/intro-start.md

@@ -1,6 +1,7 @@
 ---
 title: Getting started
 id: intro-start
+slug: /
 ---
 
 Sonar is an open source framework to manage, annotate, and full-text search through data including media files. It uses peer-to-peer technology to replicate and share collections. Sonar can be used to easily develop decentralized applications.

docusaurus.config.js

@@ -1,3 +1,4 @@
+const p = require('path')
 module.exports = {
   title: 'Sonar',
   tagline: 'A peer to peer database and search engine',
@@ -9,28 +10,33 @@ module.exports = {
   themeConfig: {
     prism: {
       theme: require('prism-react-renderer/themes/github'),
-      darkTheme: require('prism-react-renderer/themes/dracula'),
+      darkTheme: require('prism-react-renderer/themes/dracula')
     },
     navbar: {
       title: 'Sonar',
       // logo: {
       //   alt: 'My Site Logo',
       //   src: 'img/logo.svg',
       // },
-      links: [
+      items: [
         {
-          to: 'docs/',
+          to: 'docs',
           activeBasePath: 'docs',
           label: 'Docs',
-          position: 'left',
+          position: 'left'
+        },
+        {
+          href: '/apidocs-client',
+          target: '_blank',
+          label: 'Client API docs'
         },
-        {to: 'blog', label: 'Blog', position: 'left'},
+        { to: 'blog', label: 'Blog', position: 'left' },
         {
           href: 'https://github.com/arso-project/sonar',
           label: 'Github',
-          position: 'right',
-        },
-      ],
+          position: 'right'
+        }
+      ]
     },
     footer: {
       style: 'dark',
@@ -79,31 +85,63 @@ module.exports = {
         //   ],
         // },
       ],
-      copyright: `Copyright © ${new Date().getFullYear()} arso collective`,
-    },
+      copyright: `Copyright © ${new Date().getFullYear()} arso collective`
+    }
   },
   presets: [
     [
       '@docusaurus/preset-classic',
       {
         docs: {
           // It is recommended to set document id as docs home page (`docs/` path).
-          homePageId: 'intro-start',
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
-          editUrl:
-            'https://github.com/arso-project/sonar-docs/edit/master/',
+          editUrl: 'https://github.com/arso-project/sonar-docs/edit/master/'
         },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
           editUrl:
-            'https://github.com/arso-project/sonar-docs/edit/master/blog/',
+            'https://github.com/arso-project/sonar-docs/edit/master/blog/'
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
-        },
-      },
-    ],
+          customCss: require.resolve('./src/css/custom.css')
+        }
+      }
+    ]
   ],
-};
+  plugins: [
+    // [
+    //   'docusaurus-plugin-typedoc-api',
+    //   {
+    //     minimal: false,
+    //     typedocOptions: {
+    //       logLevel: 'Verbose',
+    //       excludePrivate: true
+    //     },
+    //     // projectRoot: p.join(__dirname, '..', 'sonar'),
+    //     // exclude: ['**/examples/**', '**/dist/**'],
+    //     // packages: [
+    //     //   { path: 'packages/client', entry: 'index.ts' },
+    //     //   { path: 'packages/react', entry: 'index.ts' }
+    //     // ]
+    //     projectRoot: p.join(__dirname, '..', 'sonar'),
+    //     packages: ['packages/client'],
+    //     // packages: [
+    //     //   {
+    //     //     path: '.',
+    //     //     entry: 'index.ts',
+    //     //     label: 'Client'
+    //     //   }
+    //     // ],
+    //     // Monorepo
+    //     // packages: ['packages/client'],
+    //     // Polyrepo
+    //     // packages: [
+    //     //   { path: 'packages/client', entry: 'index.ts' },
+    //     //   { path: 'packages/react', entry: 'index.ts' }
+    //     // ],
+    //   }
+    // ]
+  ]
+}