Overview The gdb() function is an async factory function that creates and configures a GenosDB database connection. It serves as the entry point for all GenosDB operations.
Signature await gdb ( name : string , options ?: DatabaseOptions ): Promise < GDB >
Parameters Database name used for local storage and P2P synchronization.
Configuration options for the database instance. Enables real-time P2P networking and relay connections. Pass true for defaults or an object to customize: Custom list of secure WebSocket relay URLs for Nostr peer discovery.
Configuration for TURN servers:
urls: Single string or array of TURN server URLsusername: Authentication usernamecredential: Authentication password Enable Cellular Mesh overlay for massive scalability. Pass true for defaults or configure:
cellSize: "auto" or fixed number (default: "auto")bridgesPerEdge: Redundancy between cells (default: 2)maxCellSize: Upper limit per cell (default: 50)targetCells: Target number of cells (default: 100)debug: Enable debug logging (default: false) Enables and configures the Security Manager for RBAC, ACLs, and identity management. Array of authorized Ethereum addresses with superadmin privileges. Mandatory when enabling SM.
Custom role definitions with permissions and inheritance.
Enable Access Control Lists for node-level permissions (default: false).
Load the AI module for enhanced functionality.
Load the Natural Language Query module for prompt-based queries.
Load the Radix Index module for prefix-based searches.
Load the Inverted Index module for full-text search.
Load the Geo module for spatial queries ($near, $bbox operators).
Load the Audit module for content policy enforcement. Custom audit policy prompt (e.g., “detect offensive or inappropriate language”).
Optional encryption key for securing database content.
Debounce delay in milliseconds for saving to persistent storage. Higher values reduce disk I/O but increase data loss risk on crashes.
Maximum number of recent operations in the operation log for delta-based P2P synchronization. Larger values enable efficient sync after longer disconnections but consume more memory.
Return Value A configured GenosDB instance ready for data operations.
Examples Basic Initialization import { gdb } from "genosdb" const db = await gdb ( "my-db" )
With Password Encryption const secureDb = await gdb ( "secure-db" , { password: "secret" })
Enable P2P Networking const db = await gdb ( "my-db" , { rtc: true })
Custom Relay Configuration const db = await gdb ( "my-db" , { rtc: { relayUrls: [ "wss://relay1.example.com" , "wss://relay2.example.com" ] } })
TURN Server Configuration const db = await gdb ( "my-db" , { rtc: { turnConfig: [ { urls: [ "turn:your-turn-server.ok:1979" ], username: "username" , credential: "password" } ] } })
Cellular Mesh for Massive Scale // Default cellular mesh const db = await gdb ( "my-db" , { rtc: { cells: true } }) // Custom cellular configuration const db = await gdb ( "my-db" , { rtc: { cells: { cellSize: "auto" , bridgesPerEdge: 2 , maxCellSize: 50 , targetCells: 100 , debug: false } } })
Enable Security Manager const db = await gdb ( "my-db" , { rtc: true , // Required for SM sm: { superAdmins: [ "0x1234..." , "0x5678..." ] } })
Enable Multiple Modules const db = await gdb ( "my-db" , { rtc: true , nlq: true , // Natural Language Queries rx: true , // Radix Index geo: true , // Geo-spatial queries audit: { prompt: "detect offensive or inappropriate language" } })
const db = await gdb ( "my-db" , { saveDelay: 500 , // Reduce disk writes oplogSize: 100 // Support longer offline periods })
Best Practices Use top-level await in modern environments (<script type="module">) to avoid unnecessary async function wrappers: // ✅ Recommended import { gdb } from "genosdb" const db = await gdb ( "my-app" ) // ❌ Avoid unless needed for user actions async function init () { const db = await gdb ( "my-app" ) }
When enabling the Security Manager, rtc: true is required as SM relies on the Real-Time Communication module for cryptographic signing and verification of P2P operations.
