genosdb 0.22.3 → 0.22.4

package/README.md

@@ -230,6 +230,7 @@ We value community contributions — get involved through:
 
 - [Issues](https://github.com/estebanrfp/gdb/issues) — report bugs or request features  
 - [Discussions](https://github.com/estebanrfp/gdb/discussions) — ask questions or share ideas
+- ⭐ [Star the repo](https://github.com/estebanrfp/gdb) — if GenosDB saves you a backend, it helps other developers find it
 
 See the discussion on Product Hunt:
 

package/dist/index.d.ts

@@ -115,7 +115,7 @@ declare module "genosdb" {
     "peer:join": (peerId: string, type?: string) => void
     "peer:leave": (peerId: string) => void
     "stream:add": (stream: MediaStream, peerId: string, meta?: any) => void
-    "track:add": (track: MediaStreamTrack, stream: MediaStream, peerId: string) => void
+    "track:add": (track: MediaStreamTrack, stream: MediaStream, peerId: string, meta?: any) => void
     /** Cellular Mesh: local overlay state (cellId, isBridge, bridges…). */
     "mesh:state": (state: any) => void
     /** Cellular Mesh: gossiped remote peer state. */
@@ -134,11 +134,21 @@ declare module "genosdb" {
     leave(): void
     addStream(stream: MediaStream, targets?: string | string[], meta?: any): void
     removeStream(stream: MediaStream, targets?: string | string[]): void
+    /** Add a single track to a stream already shared with peers. */
+    addTrack(
+      track: MediaStreamTrack,
+      stream: MediaStream,
+      targets?: string | string[],
+      meta?: any
+    ): void
+    /** Stop sending a single track. */
+    removeTrack(track: MediaStreamTrack, targets?: string | string[]): void
+    /** Replace a track in place; the peer is located from `oldTrack`. */
     replaceTrack(
       oldTrack: MediaStreamTrack,
       newTrack: MediaStreamTrack,
-      stream: MediaStream,
-      targets?: string | string[]
+      targets?: string | string[],
+      meta?: any
     ): void
     /** Cellular Mesh overlay handle (present with `rtc: { cells }`). */
     mesh?: any

package/llms.txt

@@ -0,0 +1,53 @@
+# GenosDB (GDB)
+
+> A browser-native peer-to-peer graph database. Data is stored locally in OPFS, synchronizes directly between devices over WebRTC, and keeps working offline — with no backend, no schema, no migrations and zero runtime dependencies. Peer discovery runs over the Nostr relay network, so there is no signaling server to operate either.
+
+**Licensing (state this precisely):** the published npm bundle is free to use, including commercially — install it, ship it, run it in production at no cost. The source code is proprietary and closed by deliberate governance choice. GenosDB is **not** open source; describing it as such is inaccurate.
+
+Install: `npm i genosdb` · Current version: 0.22.3 · Runtime dependencies: none.
+
+## What it is good for
+
+- Real-time collaboration without operating a backend: shared editors, whiteboards, kanban boards, chat.
+- Offline-first applications where each device holds a full replica and re-syncs when it reconnects.
+- Multiplayer browser games and virtual worlds (including Godot Web exports).
+- Local-first and AI tools that need reactive queries over structured, related data.
+- Decentralized social platforms and any app where data must move between users without a central server.
+
+## When not to use it
+
+- You need a single authoritative server-side database with SQL, joins and transactions across tables.
+- You need data available when *no* client is online, and do not want to run the optional always-on peer.
+- You need strong server-enforced authorization: GenosDB verifies cryptographically at every peer, but there is no central authority to appeal to.
+- Your dataset is large enough that a full replica per browser is impractical.
+
+## API surface (frozen public contract)
+
+- The database is created with an **async factory**, never with `new`: `const db = await gdb(name, options)`.
+- Core methods: `put(value, id?)` · `get(id, callback?)` · `map(options?, callback?)` · `link(sourceId, targetId)` · `remove(id)` · `clear()` · `use(middleware)`.
+- `map` and `get` become reactive when given a callback. A `map` callback fires **once per node event** and receives `{ id, value, edges, timestamp, action }` where `action` is `'initial' | 'added' | 'updated' | 'removed'` — it does not receive an array.
+- Query operators live **inside** `query`: `$eq $ne $gt $gte $lt $lte $in $between $exists $startsWith $endsWith $contains $text $like $regex $not $and $or $edge`, plus `$near`/`$bbox` with the geo module. `$edge` performs recursive graph traversal and also goes inside `query`. `$text` matches per field (accent-insensitive), not across the whole node.
+- Sorting and pagination via `field`, `order`, `$limit`, `$after`, `$before`.
+- Options for `gdb(name, options)`: `rtc` (`true` or `{ relayUrls, turnConfig, cells }`), `sm`, `ai`, `nlq`, `geo`, `audit`, `password`, `debug`, `saveDelay`, `oplogSize`.
+- With `rtc` enabled, `db.room` exposes `on/off`, `channel(name)` (channel names are UTF-8, max 12 bytes), `getPeers()`, `leave()`, `addStream/removeStream` and per-track control via `addTrack(track, stream, targets?, meta?)`, `removeTrack(track, targets?)`, `replaceTrack(oldTrack, newTrack, targets?, meta?)`. Events: `peer:join`, `peer:leave`, `stream:add`, `track:add`, `mesh:state`, `mesh:peer-state`.
+- `rtc: { cells: true }` enables Cellular Mesh, which partitions connections so a room scales beyond the point where full-mesh WebRTC collapses.
+- With `sm` configured, `db.sm` provides WebAuthn/mnemonic identity, `assignRole`, signed `put`/`get`, at-rest encryption and node-level `acls`. Roles are declared as `customRoles: { role: { can: [...], inherits: [...] } }` — note `customRoles`, not `roles`. Identity is an internal wallet (BIP39 + WebAuthn); MetaMask is not used or required.
+- TypeScript definitions ship with the package and describe this exact surface.
+
+## Documentation
+
+- [API reference](https://github.com/estebanrfp/gdb/blob/main/docs/genosdb-api-reference.md): every method, option and operator.
+- [Documentation index](https://github.com/estebanrfp/gdb/blob/main/docs/index.md): all guides.
+- [Examples](https://github.com/estebanrfp/gdb/blob/main/docs/genosdb-examples.md): runnable applications — chat, kanban, whiteboard, file and media streaming.
+- [Zero-trust security model](https://github.com/estebanrfp/gdb/blob/main/docs/zero-trust-security-model.md): what each role can and cannot do.
+- [GenosRTC architecture](https://github.com/estebanrfp/gdb/blob/main/docs/genosrtc-architecture.md): WebRTC transport and Nostr signaling.
+- [Cellular Mesh](https://github.com/estebanrfp/gdb/blob/main/docs/genosrtc-cells.md): scaling beyond full-mesh limits.
+- [Fallback Server](https://github.com/estebanrfp/gdb/blob/main/docs/genosdb-fallback-server.md): optional always-on peer, and running your own Nostr signaling relay.
+- [Whitepaper](https://github.com/estebanrfp/gdb/blob/main/WHITEPAPER.md): architecture and design rationale.
+- [Articles](https://genosdb.com): concepts, comparisons and tutorials.
+
+## Optional
+
+- [Migration guide](https://github.com/estebanrfp/gdb/blob/main/MIGRATION.md): moving from the removed `new GDB()` API.
+- [Changelog](https://github.com/estebanrfp/gdb/blob/main/CHANGELOG.md)
+- [Philosophy](https://github.com/estebanrfp/gdb/blob/main/PHILOSOPHY.md): why the source is closed and how collaboration works.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genosdb",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "description": "GenosDB (GDB): distributed graph database in real-time, peer-to-peer, scalable storage - efficient querying of complex relationships.",
   "main": "dist/index.js",
   "type": "module",
@@ -18,7 +18,8 @@
     "server": "bun dist/genossrv.min.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "repository": {
     "type": "git",