update article

markdown/The Bulding Blocks of Peer to Peer.md

@@ -481,7 +481,121 @@ console.log('Current core length:', core.length)
 
 Hypercore’s robust API and design make it the cornerstone of a secure, decentralized data ecosystem.
 
+## HyperDB: Database Built for P2P and Local Indexing
 
+HyperDB is a versatile database engine designed to serve both peer-to-peer applications and local indexing needs. Whether you’re looking to build a distributed, collaborative data store using Hyperbee or need a fast, local-only database backed by RocksDB, HyperDB provides a unified, high-level API that makes it easy to work with structured data.
+
+### Installation
+
+Install HyperDB via npm:
+
+```bash
+npm install hyperdb
+```
+
+### Usage
+
+Before you start, generate your database definition using the builder. This definition specifies the schemas and collections you want to work with. (For now, see the example in the `./example` directory.)
+
+You can then boot your database using the same definition for both fully P2P and local-only scenarios:
+
+```javascript
+const HyperDB = require('hyperdb')
+
+// Choose your engine:
+// For a local-only database backed by RocksDB:
+const db = HyperDB.rocks('./my-rocks.db', require('./my-definition'))
+
+// Alternatively, for a P2P database backed by Hyperbee:
+// const db = HyperDB.bee(hypercore, require('./my-definition'), [options])
+
+console.log('Database initialized!')
+```
+
+It’s that simple.
+
+### API Overview
+
+HyperDB exposes a rich set of methods to query, update, and manage your data:
+
+- **Database Creation**
+  - `db = Hyperdb.bee(hypercore, definition, [options])`  
+    Create a P2P database powered by Hyperbee.
+  - `db = Hyperdb.rocks(path, definition, [options])`  
+    Create a local-only database backed by RocksDB.
+
+- **Querying**
+  - **Find Documents:**  
+    ```javascript
+    const queryStream = db.find(collectionOrIndex, query, [options])
+    ```
+    The `query` object follows this pattern:
+    ```js
+    {
+      gt: { /* lower bound (exclusive) */ },
+      gte: { /* lower bound (inclusive) */ },
+      lt: { /* upper bound (exclusive) */ },
+      lte: { /* upper bound (inclusive) */ }
+    }
+    ```
+    And `options` may include:
+    ```js
+    {
+      limit,   // maximum number of results
+      reverse  // whether to stream in reverse order
+    }
+    ```
+    *Note:* The query operates on a snapshot—any inserts or deletes made while the query stream is active will not affect the current results.
+    
+    - **Stream Helpers:**
+      - `all = await queryStream.toArray()` — collect all entries.
+      - `one = await queryStream.one()` — retrieve the last entry.
+    
+  - **Convenience Methods:**
+    - `doc = await db.findOne(collectionOrIndex, query, [options])`  
+      *Alias for:* `await queryStream.one()`
+    - `doc = await db.get(collection, query)`  
+      Get a single document from a collection.
+    - `{ count } = await db.stats(collectionOrIndex)`  
+      Get statistics for a collection or index.
+
+- **Modifying the Database**
+  - **Inserting and Deleting:**
+    ```javascript
+    await db.insert(collection, doc)
+    await db.delete(collection, query)
+    ```
+    *Note:* You need to call `await db.flush()` later to persist these changes.
+  
+  - **Checking for Updates:**
+    ```javascript
+    const updated = db.updated([collection], [query])
+    ```
+    Returns a boolean indicating whether the database (or a specific record) has been updated.
+
+- **Snapshot and Transaction Management**
+  - `await db.flush()` — persist all pending changes.
+  - `db.reload()` — reload the internal snapshot and clear memory state.
+  - `const snapshot = db.snapshot()` — create a read-only snapshot locked in time.
+  - `const txn = db.transaction()` — create a writable snapshot; flushing this snapshot updates the main instance.
+  - `await db.close()` — close the database (remember to close any snapshots you’ve created).
+
+### Builder API
+
+The builder API lets you define the structure of your database. Each field in the definition file is an object that specifies its characteristics:
+
+```javascript
+{
+  name: 'field-name',
+  type: 'uint',       // a compact-encoding type, or a reference to another encoding defined in the builder file
+  required: true,     // set to false for optional fields
+  array: false        // set to true to store an array of this type
+}
+```
+
+This flexible schema definition allows you to easily declare collections, indices, and relationships tailored to your application’s needs.
+
+HyperDB’s rich feature set makes it an excellent choice for building robust, scalable databases that work seamlessly in both decentralized and local environments. Experiment with its flexible API to build custom queries, manage snapshots, and implement transactions effortlessly. Happy coding!
 
 ## Integrating the Ecosystem: Real-World Applications