Skip to main content

​
JavaScript SDK

Complete guide to using Cocobase with JavaScript and TypeScript applications.

​
Installation

npm: 
npm install cocobase
yarn: 
yarn add cocobase
pnpm: 
pnpm add cocobase

​
Quick Start

​
Initialize Cocobase

import { Cocobase } from "cocobase";

const db = new Cocobase({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.cocobase.buzz", // Optional, defaults to this
});

​
Basic Operations

// List documents
const docs = await db.listDocuments("posts");

// Get single document
const doc = await db.getDocument("posts", "doc-id");

// Create document
const created = await db.createDocument("posts", {
  title: "My First Post",
  content: "Hello World!",
});

// Update document
await db.updateDocument("posts", "doc-id", {
  title: "Updated Title",
});

// Delete document
await db.deleteDocument("posts", "doc-id");

​
Querying Data

​
Simple Filters

// Find active users older than 18
const users = await db.listDocuments("users", {
  filters: {
    status: "active",
    age__gt: 18,
  },
});

​
Query Builder

import { QueryBuilder } from "cocobase";

const users = await db.listDocuments("users", {
  query: new QueryBuilder()
    .where("status", "active")
    .whereGreaterThan("age", 18)
    .whereContains("email", "@gmail.com")
    .orderByDesc("createdAt")
    .limit(10),
});

​
Operators Reference

​
Comparison Operators

OperatorFilter KeyExample
Equalfield{ status: "active" }
Greater Thanfield__gt{ age__gt: 18 }
Greater or Equalfield__gte{ age__gte: 18 }
Less Thanfield__lt{ age__lt: 65 }
Less or Equalfield__lte{ age__lte: 65 }
Not Equalfield__ne{ status__ne: "deleted" }

​
String Operators

OperatorFilter KeyExample
Containsfield__contains{ title__contains: "javascript" }
Starts Withfield__startswith{ email__startswith: "admin" }
Ends Withfield__endswith{ domain__endswith: ".com" }

​
Array Operators

OperatorFilter KeyExample
In Arrayfield__in{ status__in: "active,pending" }
Not In Arrayfield__notin{ status__notin: "deleted,archived" }

​
Sorting and Pagination

​
Sorting

// Sort by creation date (newest first)
const posts = await db.listDocuments("posts", {
  filters: {
    orderBy: "createdAt",
    order: "desc",
  },
});

​
Pagination

// Get page 3 (20 items per page)
const posts = await db.listDocuments("posts", {
  filters: {
    limit: 20,
    offset: 40,
  },
});

​
Type Safety with TypeScript

​
Define Your Types

interface Book {
  title: string;
  author: string;
  price: number;
  publishedAt?: string;
}

// Typed list
const books = await db.listDocuments<Book>("books");

// Full type safety
books.forEach((doc) => {
  console.log(doc.data.title); // TypeScript knows this is a string
  console.log(doc.data.price); // TypeScript knows this is a number
});

// Typed single document
const book = await db.getDocument<Book>("books", "doc-id");
console.log(book.data.author);

​
Create Typed Documents

const newBook: Book = {
  title: "Clean Code",
  author: "Robert Martin",
  price: 45.99,
};

const created = await db.createDocument<Book>("books", newBook);
console.log(created.id);

​
Authentication

​
Email/Password

// Register
await db.auth.register({
  email: "[email protected]",
  password: "securePassword123",
});

// Get user after registration
const user = await db.auth.getUser();
console.log("User ID:", user.id);

// Login
await db.auth.login({
  email: "[email protected]",
  password: "securePassword123",
});

// Get user after login
const loggedInUser = await db.auth.getUser();

// Logout
await db.auth.logout();

// Check current user
const currentUser = db.auth.currentUser;

​
OAuth

// Google OAuth
await db.auth.signInWithGoogle();
const user = await db.auth.getUser();

// GitHub OAuth
await db.auth.signInWithGitHub();
const user = await db.auth.getUser();

​
Real-time Data

​
Watch Collection

// Watch for changes
const unsubscribe = db.watchCollection("posts", (event) => {
  console.log("Event type:", event.type); // created, updated, deleted
  console.log("Document:", event.document);
});

// Stop watching
unsubscribe();

​
Watch Document

const unsubscribe = db.watchDocument("posts", "doc-id", (document) => {
  console.log("Document updated:", document.data);
});

// Stop watching
unsubscribe();

​
File Storage

​
Upload Files

// Upload a file
const file = document.getElementById("fileInput").files[0];
const uploaded = await db.storage.upload(file);
console.log("File URL:", uploaded.url);

// Upload with document
const doc = await db.createDocumentWithFiles("posts", {
  title: "Post with Image",
  content: "Check out this image!",
}, {
  image: file,
});

​
Download Files

const fileUrl = await db.storage.getUrl("file-id");

​
Error Handling

try {
  const doc = await db.getDocument("posts", "non-existent-id");
} catch (error) {
  if (error.code === "NOT_FOUND") {
    console.log("Document not found");
  } else if (error.code === "UNAUTHORIZED") {
    console.log("Not authorized");
  } else {
    console.log("Error:", error.message);
  }
}

​
Best Practices

​
1. Always Use Types

// Good
const books = await db.listDocuments<Book>("books");

// Avoid
const books = await db.listDocuments("books");

​
2. Always Set Limits

// Good
const posts = await db.listDocuments("posts", {
  filters: { limit: 20 },
});

// Bad - could return thousands
const posts = await db.listDocuments("posts");

​
3. Handle Errors

try {
  const doc = await db.getDocument("posts", id);
  return doc;
} catch (error) {
  console.error("Failed to fetch:", error);
  return null;
}

​
4. Use Environment Variables

const db = new Cocobase({
  apiKey: process.env.COCOBASE_API_KEY,
});

​
Next Steps