Skip to main content

Driver Overview

This documentation provides a complete guide to using the LioranDB V2 Pre-Alpha TypeScript/JavaScript Driver. It covers installation, connection setup, supported database operations, API usage, and essential workflows for integrating LioranDB into TypeScript and JavaScript applications.

Install @liorandb/driver@2.0.6
npm i @liorandb/driver@2.0.6

Node.js and package basics​

  • Package name: @liorandb/driver
  • Current documented npm version: 2.0.6
  • Runtime module format: ESM
  • Node.js requirement: 18+
  • Native fetch is expected by the HTTP transport

What the package exports​

The source export barrel at src/index.ts exposes these major areas:

  • client entrypoints: LioranDBClient, MongoClient
  • handles: Db, Collection
  • cursors: FindCursor, AggregationCursor
  • auth/admin services: AuthService, UsersService, RolesService, ClusterService, BackupsService, SettingsService
  • config helpers: parseConnectionString(), normalizeMongoClientConfig(), normalizeLioranDBClientConfig(), isNormalizedConfig(), defaultSchemeForProtocol()
  • transports: HttpTransport, HttpDataTransport, GrpcDataTransport
  • errors and warning codes
  • the full exported type surface for auth, config, admin payloads, transport diagnostics, and CRUD

The real mental model​

LioranDBClient
  -> Db
    -> Collection<T>
      -> CRUD methods
      -> FindCursor<T>
      -> AggregationCursor<TResult>

LioranDBClient
  -> auth
  -> users
  -> roles
  -> cluster
  -> backups
  -> settings

LioranDBClient​

This is the root object. It owns:

  • configuration normalization
  • HTTP transport creation
  • gRPC transport resolution when needed
  • token storage through TokenManager
  • auth convenience methods
  • service handles
  • active cursor lifecycle
  • diagnostic headers and response observers

Db​

This scopes work to one database and exposes:

  • collection(name)
  • createCollection(name)
  • listCollections()
  • dropCollection(name)
  • dropDatabase()
  • query(collection, filter?, options?)

Collection<TSchema>​

This is the main application handle for document work. It exposes:

  • insertOne()
  • insertMany()
  • find()
  • findOne()
  • countDocuments()
  • createIndex()
  • createTextIndex()
  • listIndexes()
  • dropIndex()
  • findManyByIds()
  • updateOne()
  • updateMany()
  • deleteOne()
  • deleteMany()
  • aggregate()
  • drop()

The docs test currently verifies all of the following against a live server:

  • secondary index creation with createIndex()
  • text index creation with createTextIndex()
  • index-aware range queries such as {docNumber: {$gte: 4}}
  • text-index-backed $text queries
  • countDocuments() with and without filters
  • index deletion with dropIndex()

FindCursor<TSchema>​

This is a chainable, async-iterable cursor abstraction. It supports:

  • query-shaping methods such as filter(), limit(), skip(), sort(), project()
  • execution methods such as next(), tryNext(), hasNext(), toArray()
  • iteration helpers such as forEach() and map()
  • lifecycle helpers such as rewind(), clone(), and close()

AggregationCursor<TResult>​

This is the aggregation equivalent. It is also async-iterable and supports:

  • next()
  • tryNext()
  • hasNext()
  • toArray()
  • forEach()
  • map()
  • rewind()
  • clone()
  • close()

First end-to-end example​

import {LioranDBClient} from "@liorandb/driver";

type User = {
  _id?: string;
  email: string;
  active: boolean;
  age: number;
};

const client = await LioranDBClient.connect(
  "liorandb://admin:password@127.0.0.1:27018/default",
);

try {
  const db = client.db("default");
  const users = db.collection<User>("users");

  const inserted = await users.insertOne({
    email: "user@example.com",
    active: true,
    age: 18,
  });

  await users.createIndex("age");
  await users.createTextIndex("email");

  const found = await users.findOne({email: "user@example.com"});
  const activeCount = await users.countDocuments({active: true});
  const textMatches = await users.find({
    $text: {$search: "user", $field: "email"},
  }).toArray();

  const activeUsers = await users
    .find({active: true})
    .sort({email: 1})
    .limit(20)
    .toArray();

  console.log({
    insertedId: inserted.insertedId,
    found,
    activeCount,
    textMatches: textMatches.length,
    pageCount: activeUsers.length,
  });
} finally {
  await client.close();
}

Representative output:

Application output
{
  "insertedId": "01K2EXAMPLE",
  "found": {
    "_id": "01K2EXAMPLE",
    "email": "user@example.com",
    "active": true,
    "age": 18
  },
  "activeCount": 1,
  "pageCount": 1
}

How the driver executes that example​

  1. LioranDBClient.connect(...) parses the connection string and normalizes it into an immutable config object.
  2. The client checks server availability using HTTP when an HTTP-capable address exists.
  3. If credentials are present, auth.login() runs automatically during connect().
  4. client.db("default") creates a Db handle.
  5. db.collection<User>("users") creates a typed Collection<User>.
  6. insertOne() serializes the document and delegates to the active data transport.
  7. findOne() issues a one-shot read request.
  8. countDocuments() runs a server-side count for the matching filter.
  9. find(...).sort(...).limit(...).toArray() creates a FindCursor, applies query options, fetches pages, and materializes the final result.
  10. close() logs out when configured, closes active transports, and closes active cursors.

Supported connection schemes​

The connection parser accepts:

liorandb://
liorandb+http://
liorandb+https://
http://
https://
grpc://

Examples:

liorandb://admin:password@127.0.0.1:27018/default
liorandb://admin:encoded%40password@client.db.example.com:443/default
liorandb+https://admin:password@db.example.com/default
grpc://db.example.com:443/default

Public API areas worth learning in order​

  1. LioranDBClient configuration and lifecycle
  2. Db and Collection<TSchema>
  3. FindCursor and AggregationCursor
  4. auth and admin service handles
  5. exports, types, transports, and error classes