Nodb NPM is a wrapper for nodb API. It allows you to do CRUD operations over your Postgres database via API directly. Nodb keeps track of vector embeddings using pgvector so that you can do retrieval-augmented generation (RAG) using vector search. Nodb offers real-time updates using websockets by connecting to the Nodb API and subscribing to changes.
Nodb supports both ESM and CommonJS modules, allowing you to integrate it seamlessly into your projects using either module system and you can use it with npm, yarn, bun, etc.
First install the NPM package (e.g. with npm, yarn, pnpm, bun):
npm install nodb-js-sdkTo begin using NodbSDK, import the Nodb class:
import Nodb from "nodb-js-sdk";
//OR
const Nodb = require("nodb-js-sdk");If you're using import you should add "type": "module" to package.json. You need to create an instance of Nodb now:
const nodb = new Nodb({
baseUrl: "http://localhost:3000",
});NodbSDK works with the following hierarchical structure:
- Application: The top-level container
- Environments: Belong to an application
- Entities: Belong to an environment
One application can contain multiple environments, and each environment can contain multiple entities.
To create your first application with an environment:
const application = await nodb.createApplication({
appName: "your-application-name",
envName: "your-environment-name",
});If you don't specify an envName a default environment is created for you called dev.
After creating an application, you'll receive tokens for both the application and the environment:
// Token for your application (broader permission scope)
const appToken = application.applicationTokens[0].key;
// Token for your environment (limited scope of permissions for the environment)
const envToken = application.environmentTokens[0].key;You can set a token globally for all subsequent operations:
nodb.setToken(appToken);Alternatively, you can provide tokens individually for each method call. If both a global token and a method-specific token are provided, the method-specific token takes precedence.
Let's write our first entities. Prepare some data that you'll import:
// seed.ts
type Todo = {
task: string;
priority?: "high" | "low";
completed: boolean;
}
const todos:Todo[] = [
{
task: "Finish report",
priority: "high",
completed: false,
},
{
task: "Buy groceries",
completed: false,
},
{
task: "Call mom",
completed: false,
},
];Writing entities is done using writeEntities method for example using todos entity:
const ids = await nodb.writeEntities({
appName: "your-application-name",
envName: "your-environment-name",
entityName: "your-entity-name",
payload: todos
});Or with then/catch:
nodb.writeEntities({
appName: "your-application-name",
envName: "your-environment-name",
entityName: "your-entity-name",
payload: todos
}).then(console.log); // get the idsLet's make a sample inquiry using .inquire method, useful for RAG applications:
const { answer } = await nodb.inquire({
appName: "your-application-name",
envName: "your-environment-name",
inquiry: "Which todo has highest priority?",
});
//Or
nodb.inquire({
appName: "your-application-name",
envName: "your-environment-name",
inquiry: "Which todo has highest priority?",
}).then(console.log);The response returned from inquire method has the following definition:
{
answer: "Finishing report has highest priority.";
}Our SDK provides WebSocket support for monitoring write, update, and delete events on your Nodb API. You can easily connect to the WebSocket with the connectToSocket method:
Example usage:
nodb.connectToSocket({
appName: "your-app-name",
envName: "your-env-name", // Optional: Listen to all events for an application if omitted.
socketBaseUrl: "ws://localhost:3000", // Optional: If not provided, we automatically convert the base URL for you.
token: "yourToken" // Optional: If omitted, we use the previously provided token. An error will be thrown if no token is provided and none has been set before.
})Upon a successful connection, a message will appear in the console, indicating that you are now connected to the WebSocket. You will start receiving real-time updates about your application or environment.
To close the WebSocket connection, simply call:
nodb.disconnectFromSocket()With these methods, you can seamlessly integrate WebSocket functionality into your application for real-time updates.
We are using jest to run e2e tests. You can run them with
npm run testFor testing we have a .env.test file where the only env variable that is specified is:
NODB_BASE_URL=The Nodb class provides methods for interacting with a NoDB (NoSQL Database) backend via HTTP and WebSocket connections. It extends the NodbWebSocket class to support WebSocket functionality.
constructor({ token, baseUrl }: NodbConstructor)- Parameters:
token(optional,string): Authentication token for API requests.baseUrl(string): Base URL for the API endpoints.
setToken(token: string): voidasync writeEntities(props: BaseAPIProps & PostEntityRequestBody): Promise<string[]>async writeEntity(props: BaseAPIProps & { payload: EntityBody }): Promise<string>async updateEntities(props: BaseAPIProps & PatchRequestBody): Promise<string[]>async updateEntity(props: BaseAPIProps & { payload: EntityBodyWithId }): Promise<string>async replaceEntities(props: BaseAPIProps & PatchRequestBody): Promise<string[]>async replaceEntity(props: BaseAPIProps & { payload: EntityBodyWithId }): Promise<string>async deleteEntities(props: BaseAPIProps): Promise<number>async deleteEntity(props: BaseAPIProps & EntityId): Promise<boolean>async getEntity(props: BaseAPIProps & EntityId): Promise<Entity>async getEntities(props: BaseAPIProps): Promise<EntityResponse>async inquire(props: Inquiry & Pick<BaseAPIProps, "appName" | "envName" | "token">): Promise<{ answer: string }>async createApplication(props: PostApplicationBody): Promise<PostApplicationResponse>async createEnvironmentInApp(props: PostEnvironmentBody): Promise<PostEnvironmentResponse>async deleteEnvironmentFromApp(props: { appName: string; envName: string; token?: string }): Promise<boolean>async deleteApplication(props: { appName: string; token?: string }): Promise<boolean>async createApplicationToken(props: { appName: string; permission: TokenPermissions; token?: string }): Promise<PostApplicationTokenResponse>async createEnvironmentToken(props: { appName: string; envName: string; permission: TokenPermissions; token?: string }): Promise<PostEnvironmentTokenResponse>async revokeApplicationToken(props: { appName: string; tokenToBeRevoked: string; token?: string }): Promise<boolean>async revokeEnvironmentToken(props: { appName: string; envName: string; tokenToBeRevoked: string; token?: string }): Promise<boolean>connectToSocket(props: { appName: string; envName?: string; token?: string; socketBaseUrl?: string }): voiddisconnectFromSocket(): void