Node.js SDK

The @plugport/sdk package provides a unified API for Node.js and TypeScript applications. While its syntax is intentionally designed to mirror the MongoDB driver for zero-learning-curve familiarity, it acts as a universal bridge connecting to PlugPort's verifiable multi-protocol storage.

Installation

npm install @plugport/sdk
# or
pnpm add @plugport/sdk

Quick Start

import { PlugPortClient } from '@plugport/sdk';

const client = await PlugPortClient.connect('http://localhost:8080');
const db = client.db('myapp');
const users = db.collection('users');

// Insert
const result = await users.insertOne({
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
});
console.log('Inserted:', result.insertedId);

await client.close();

API Reference

PlugPortClient

PlugPortClient.connect(uri, options?)

Creates a new client and verifies the connection.

const client = await PlugPortClient.connect('http://localhost:8080', {
  apiKey: 'your-api-key',  // optional
});

Parameter	Type	Description
uri	string	Server URL (http:// or plugport://)
options.apiKey	string?	API key for authentication
options.timeout	number?	Request timeout in milliseconds (default: 30000)

client.db(name)

Returns a Database reference.

const db = client.db('myapp');

client.health()

Returns server health status.

const health = await client.health();
// { status: 'ok', uptime: 12345, version: '1.0.0', storage: {...} }

client.metrics()

Returns performance metrics snapshot.

client.close()

Closes the connection.

---

Database

db.collection(name)

Returns a typed Collection reference.

interface User {
  name: string;
  email: string;
  age: number;
}

const users = db.collection<User>('users');

db.listCollections()

Lists all collections.

const { collections } = await db.listCollections();
// [{ name: 'users', documentCount: 10, indexCount: 2 }]

---

Collection

insertOne(document)

const result = await users.insertOne({
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
});
// { acknowledged: true, insertedId: '67b2a1f0...', insertedCount: 1 }

insertMany(documents)

const result = await users.insertMany([
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
]);
// { acknowledged: true, insertedCount: 2, insertedIds: ['...', '...'] }

find(filter, options?)

// All users
const allUsers = await users.find();

// With filter
const adults = await users.find({ age: { $gte: 18 } });

// With options
const topUsers = await users.find(
  { status: 'active' },
  {
    sort: { score: -1 },
    limit: 10,
    skip: 0,
    projection: { name: 1, score: 1 },
  }
);

findOne(filter, options?)

const user = await users.findOne({ email: 'alice@example.com' });
// Returns the document or null

updateOne(filter, update, options?)

const result = await users.updateOne(
  { name: 'Alice' },
  { $set: { age: 31, updatedAt: new Date().toISOString() } },
  { upsert: false }
);
// { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }

deleteOne(filter)

const result = await users.deleteOne({ name: 'Alice' });
// { acknowledged: true, deletedCount: 1 }

deleteMany(filter)

const result = await users.deleteMany({ status: 'inactive' });
// { acknowledged: true, deletedCount: 5 }

createIndex(field, options?)

const result = await users.createIndex('email', { unique: true });
// { acknowledged: true, indexName: 'email_1' }

dropIndex(indexName)

await users.dropIndex('email_1');

listIndexes()

const { indexes } = await users.listIndexes();
// [{ name: '_id_', field: '_id', unique: true }, ...]

stats()

const stats = await users.stats();
// { documentCount: 100, indexCount: 3, storageSizeBytes: 45678 }

countDocuments(filter?)

const count = await users.countDocuments({ status: 'active' });

distinct(field, filter?)

const categories = await products.distinct('category', { inStock: true });
// ['electronics', 'clothing', 'books']

aggregate(pipeline)

Execute an aggregation pipeline. Supported stages: $match, $lookup, $project, $sort, $limit, $skip, $unwind, $count.

const results = await orders.aggregate([
  { $match: { status: 'completed' } },
  { $lookup: {
      from: 'users',
      localField: 'userId',
      foreignField: '_id',
      as: 'user',
  }},
  { $unwind: '$user' },
  { $project: { orderId: 1, total: 1, 'user.name': 1 } },
  { $sort: { total: -1 } },
  { $limit: 10 },
]);

updateMany(filter, update)

const result = await users.updateMany(
  { status: 'inactive' },
  { $set: { archived: true } },
);
console.log(result.modifiedCount); // 5

grantRole(address, role)

Grant an access role to a wallet address on this collection.

await users.grantRole('0xabc...', 1); // 1 = read, 2 = write

revokeRole(address)

Revoke access for a wallet address.

await users.revokeRole('0xabc...');

drop()

await users.drop();

Error Handling

import { PlugPortError } from '@plugport/sdk';

try {
  await users.insertOne({ email: 'alice@example.com' });
} catch (err) {
  if (err instanceof PlugPortError) {
    console.log(err.code);    // 11000 (duplicate key)
    console.log(err.message); // "Duplicate key error..."
  }
}

TypeScript Support

The SDK is fully typed. Use generics for strong typing:

interface Product {
  name: string;
  price: number;
  category: string;
  stock: number;
}

const products = db.collection<Product>('products');

// TypeScript knows the shape of documents
await products.insertOne({
  name: 'Widget',
  price: 29.99,
  category: 'electronics',
  stock: 100,
});