Documentation Index

Fetch the complete documentation index at: https://mintlify.com/estebanrfp/gdb/llms.txt

Use this file to discover all available pages before exploring further.

​

Migration Guide: from new GDB() to await gdb(...)

​

Key changes

• Support for new GDB() has been removed.
  • Initialize with the async function: const db = await gdb(name, options).
  • If you use new GDB(), an error will be thrown pointing to the correct call.
• Public operations API remains stable:
  • put, get, map, remove, link, clear keep their signatures and behavior.
• Internals exposed for module compatibility:
  • db.hybridClock, db.graph, db.syncChannel are available as read-only getters.
  • db.ready may exist for legacy uses, but prefer await gdb(...).

​

Quick migration (before → after)

​

Basic initialization

import { GDB } from 'gdb';
const db = new GDB('my-db');

import { gdb } from 'gdb';
const db = await gdb('my-db', { rtc: true }); // rtc: true for realtime comunication

​

Using map (real-time subscription)

const { unsubscribe } = await db.map(({ id, value, action }) => {
  // render
});

const { unsubscribe } = await db.map(({ id, value, action }) => {
  // render
});

​

Using get (point-in-time and reactive)

const { result } = await db.get(nodeId);
// or reactive
const { unsubscribe } = await db.get(nodeId, (node) => { /* ... */ });

const { result } = await db.get(nodeId);
// or reactive
const { unsubscribe } = await db.get(nodeId, (node) => { /* ... */ });

​

Write and delete

await db.put({ text: 'hello' });
await db.remove(nodeId);

await db.put({ text: 'hello' });
await db.remove(nodeId);

​

Security Manager (SM) and RBAC integration

​

Recommended initialization

const db = await gdb("my-db", {
  rtc: true, 
  sm: {
    superAdmins: ["0x1...", "0x2..."] // superadmin addresses
  }
});

const sm = db.sm; // provided by SM module

• sm is injected when passing { sm: { superAdmins: ['0x1...', '0x2...'] } } at initialization. Access it via db.sm.
• Internals expected by SM (now exposed): db.hybridClock, db.graph, db.syncChannel.
• Standardized actions (recommended): read, write, link, sync, delete.

​

Permission check (example)

const active = sm.getActiveEthAddress();
if (!active) throw new Error('Login required');

// if not superadmin, validate permission
await sm.executeWithPermission('delete');
await db.remove(id);

​

Browser usage (ESM)

• Using the local bundle:

<script type="module">
  import { gdb } from "../dist/index.js";

  </script>

• Using the NPM package (if applicable):

import { gdb } from 'genosdb';

​

Common pitfalls and fixes

• Error: db.map is not a function or db.put is not a function
  • Cause: using db before initialization completes.
  • Fix: use const db = await gdb('name') before calling any method.
• SM error: Cannot read properties of undefined (reading 'now')
  • Cause: module expected db.hybridClock which was not exposed.
  • Status: Fixed; hybridClock, graph, and syncChannel are exposed as getters.
• map doesn’t emit after loading the graph
  • Ensure you call await gdb(...) before db.map(...).
  • Confirm your query/$limit doesn’t filter out all nodes.

​

Migration checklist

1. Replace all occurrences of new GDB(name, options) with await gdb(name, options).
2. Ensure the first use of db always happens after await gdb(...).
3. If you use SM:
   • Initialize with { sm: { superAdmins: ['0x1...', '0x2...'] } } (mandatory superAdmins array).
   • The security context is set up automatically; no additional calls needed.
4. Review RBAC and use standardized actions (read, write, link, sync, delete).
5. Test end-to-end: initial load, put, update, remove, link, and P2P sync when applicable.

​

FAQ

• Can I still use db.ready?
  • It may exist in some contexts, but it’s not recommended. Prefer await gdb(...).
• Did map or get signatures change?
  • No. They still return { results, unsubscribe } or { result, unsubscribe } accordingly.
• How do I filter and order in map?
  • Use options: { query: {...}, field: 'timestamp', order: 'asc'|'desc', $limit, $after, $before }.

​

Full example (To‑Do List)

<script type="module">
  import { GDB } from "../dist/index.js";
  const db = new GDB('todoList');
  const { unsubscribe } = await db.map(({ id, value, action }) => { /* ... */ });
</script>

<script type="module">
  import { gdb } from "../dist/index.js";
  const db = await gdb('todoList', { rtc: true });
  const { unsubscribe } = await db.map(({ id, value, action }) => { /* ... */ });
</script>